typescript-document

Start with a one-sentence third-person summary, then add `@param name - description` with a hyphen and no type annotation, followed by `@returns` for non-void returns. Order tags as summary, `@remarks`, params, returns and throws, example, then `@category` and `@since` last.

Skip comments when the signature and name already state the whole behavior, such as trivial getters, one-line helpers, test helpers, and anonymous components. Document only exported declarations and internals with a contract the code does not show.

The `@returns` tag should name each error case in the `E` channel and explain what `None` or `Left` means for `Option` and `Either` returns. This gives callers the failure semantics the type signature alone cannot convey.

Yes, `@effect/docgen` requires a `@since` tag on every export it parses, with `enforceVersion` defaulting to true. It also uses `@category` to group exports in generated output, defaulting to `utils`, and type-checks fenced code in `@example` blocks.

Document each member of the props interface with a one-line comment, then document the component function separately with `@param props -` referencing the interface via `{@link}`. Components take no `@typeParam` since the props interface declares the generic.

A `@param` name that differs from the actual parameter name appears as an editor suggestion in `.ts` files rather than proper documentation. Ensure every parameter is documented with its exact name, or document none of them.