Stream: beginners

Topic: Linting, Fomatting and Documentation

Tobias Steckenborn (Jan 03 2024 at 08:39):

Hey there,

I'd have three quick questions:

1. Is there a plan to include a sort of linter by default, which might report on common pitfalls?
2. Is there a plan to include a formatting standard by default, so that teams avoid discussions around that? So something such as Prettier or Biome Format in the JS / TS ecosystem?
3. The way documentation is described in the Tutorial indicates that it would be quite free text. Is there a plan to have more detailed documentation possibilities w.r.t. to specific parameters and the like?

mkrieger1 (Jan 03 2024 at 09:47):

There already is a roc format command but I didn't see a description of the format it tries to create on the website.

Anton (Jan 03 2024 at 10:43):

Is there a plan to include a sort of linter by default, which might report on common pitfalls?

I think a linter probably is a good idea for the things that don't fit as compiler warnings.

Anton (Jan 03 2024 at 10:44):

Is there a plan to have more detailed documentation possibilities w.r.t. to specific parameters and the like?

I don't think we've discussed that before, what do you consider to be the key benefits of that approach?

Tobias Steckenborn (Jan 03 2024 at 11:08):

There might be some, depending on the angle you're looking at the problem and potentially the platform.

One example could be parameter specific description on hover in an editor. Another one automatic creation of documenation Let's take an example of tsdocs / jsdocs (even though to my knowledge not integrated in VSCode in this way.

/**
 * Runs all the provided effects in sequence respecting the structure provided in input.
 *
 * Supports multiple arguments, a single argument tuple / array or record / struct.
 *
 * @since 2.0.0
 * @category collecting & elements
 */

/**
 * Returns an effect that will be executed at most once, even if it is
 * evaluated multiple times.
 *
 * @example
 * import * as Effect from "effect/Effect"
 * import * as Console from "effect/Console"
 *
 * const program = Effect.gen(function* (_) {
 *   const twice = Console.log("twice")
 *   yield* _(twice, Effect.repeatN(1))
 *   const once = yield* _(Console.log("once"), Effect.once)
 *   yield* _(once, Effect.repeatN(1))
 * })
 *
 * Effect.runFork(program)
 * // Output:
 * // twice
 * // twice
 * // once
 *
 * @since 2.0.0
 * @category caching
 */

/**
 * This function returns `true` if the specified value is an `Effect` value,
 * `false` otherwise.
 *
 * This function can be useful for checking the type of a value before
 * attempting to operate on it as an `Effect` value. For example, you could
 * use `isEffect` to check the type of a value before using it as an
 * argument to a function that expects an `Effect` value.
 *
 * @param u - The value to check for being an `Effect` value.
 *
 * @returns `true` if the specified value is an `Effect` value, `false`
 * otherwise.
 *
 * @since 2.0.0
 * @category refinements
 */

This enables tools like tsdocs to structure the elements:
image.png
image.png

At the same time editors such as VSCode now also potentially show on hover details for parameters, where a description for that specific parameter could be placed:

Tobias-Steckenborn-2024-01-03-at-12.05.532x.png

I hope that get's the point across :D

Tobias Steckenborn (Jan 03 2024 at 11:09):

Tobias Steckenborn schrieb:

There might be some, depending on the angle you're looking at the problem and potentially the platform.

One example could be parameter specific description on hover in an editor. Another one automatic creation of documenation Let's take an example of tsdocs / jsdocs (even though to my knowledge not integrated in VSCode in this way.

/**
 * Runs all the provided effects in sequence respecting the structure provided in input.
 *
 * Supports multiple arguments, a single argument tuple / array or record / struct.
 *
 * @since 2.0.0
 * @category collecting & elements
 */

/**
 * Returns an effect that will be executed at most once, even if it is
 * evaluated multiple times.
 *
 * @example
 * import * as Effect from "effect/Effect"
 * import * as Console from "effect/Console"
 *
 * const program = Effect.gen(function* (_) {
 *   const twice = Console.log("twice")
 *   yield* _(twice, Effect.repeatN(1))
 *   const once = yield* _(Console.log("once"), Effect.once)
 *   yield* _(once, Effect.repeatN(1))
 * })
 *
 * Effect.runFork(program)
 * // Output:
 * // twice
 * // twice
 * // once
 *
 * @since 2.0.0
 * @category caching
 */

/**
 * This function returns `true` if the specified value is an `Effect` value,
 * `false` otherwise.
 *
 * This function can be useful for checking the type of a value before
 * attempting to operate on it as an `Effect` value. For example, you could
 * use `isEffect` to check the type of a value before using it as an
 * argument to a function that expects an `Effect` value.
 *
 * @param u - The value to check for being an `Effect` value.
 *
 * @returns `true` if the specified value is an `Effect` value, `false`
 * otherwise.
 *
 * @since 2.0.0
 * @category refinements
 */

This enables tools like tsdocs to structure the elements:
image.png
image.png

At the same time editors such as VSCode now also potentially show on hover details for parameters, where a description for that specific parameter could be placed:

Tobias-Steckenborn-2024-01-03-at-12.05.532x.png

I hope that get's the point across :D

Additionally at an outer boundary there might be benefits in creating e.g. something alike an OpenAPI spec, or a CLI help - but that's debatable and would be very reliant on the individual platform.

Anton (Jan 03 2024 at 11:15):

"show on hover details for parameters" is nice indeed! You can create a new topic in the ideas stream if you want to propose a syntax for this. If not, I can make an issue for this to explore it at a later time.

Last updated: Jul 06 2025 at 12:14 UTC