For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /packs/languages/typescript/comments.md.
Quick start

JSDoc

Use JSDoc to describe what callers cannot learn from the signature alone.

Exported and private declarations

Why

A Result type does not explain whether missing metadata returns an empty catalog or a failure. That distinction belongs in the operation's documentation.

Rules

  • MUST precede each exported function with a JSDoc block spanning multiple lines. [review]
  • MUST begin the block with an imperative description of the operation. [review]
  • MUST use @param and @returns to explain constraints and outcome behavior that the signature leaves unclear. [review]
  • MUST provide a usable @example for every symbol exposed through a public package entrypoint. [review]
  • SHOULD explain exported types and values whose role is not evident from their names. [review]
  • MUST label private functions and private implementation types with @private. [review]
  • MUST leave TypeScript type syntax out of JSDoc tags instead of repeating the signature. [review]
  • MUST document the proven safety condition immediately above an allowed non-const assertion. [review]
  • MAY leave JSDoc out of tests and focused examples in this pack. [review]

The shared principles route code-comment rationale, workarounds, and unfinished work to the engineering component.

Examples

An exported function's single-line comment is insufficient. This example documents the observable choice rather than repeating its types:

type HasEntryParams = {
  readonly entry: string
  readonly selectedFiles: readonly string[]
}

/**
 * Check whether selected content includes its declared entrypoint.
 * @param options - Entry path and selected paths, both relative to the same content root.
 * @returns Whether the exact entry path is selected.
 * @example
 * hasEntry({ entry: 'START.md', selectedFiles: ['START.md', 'guide.md'] })
 */
export function hasEntry({ entry, selectedFiles }: HasEntryParams): boolean {
  return selectedFiles.includes(entry)
}

Private implementation details use @private; keep their blocks multiline for consistency:

/**
 * @private
 */
function hasLeadingSlash(path: string): boolean {
  return path.startsWith('/')
}

[review]

Configured documentation rules cover their supported syntax. Review checks caller-facing constraints, examples, and private declaration documentation.

Enforcement

Configured documentation rules cover their supported syntax. Review checks caller-facing constraints, examples, and private declaration documentation.