TSDoc and JSDoc Authoring

When to Apply

• add or improve code comments/docs
• write TSDoc or JSDoc
• document params, return values, thrown errors, or examples
• standardize documentation style across files

Routing (Read This First)

• TypeScript APIs and typed exports:

  indexes/tsdoc-index.md

• JavaScript authoring and shape docs:

  indexes/jsdoc-authoring-index.md

• Strict consistency/lint-safe output standards:

  indexes/jsdoc-consistency-index.md

Rule 1: Choose the Correct Standard

• Use TSDoc for TypeScript code and typed public APIs.
• Use JSDoc for JavaScript code or projects using JSDoc tooling.
• Do not mix tag syntaxes from both standards in one comment block.

Workflow

1. Read the target file and identify the symbol's purpose and side effects.
2. Prefer documenting exported/public APIs first.
3. Write a one-line summary in plain language.
4. Add only meaningful tags (no empty or redundant tags).
5. Validate tag names and formatting against the relevant standard.
6. Ensure comments match actual behavior (inputs, outputs, errors, async behavior).

Authoring Rules (Both Standards)

• Describe intent and behavior, not obvious implementation details.
• Keep summaries concise and action-oriented ("Returns...", "Creates...", "Parses...").
• Document every parameter and explain what each parameter does.
• If a parameter is an object, document each object property and what it does.
• Use imperative, consistent phrasing for

  @param

  descriptions.
• Document thrown errors with

  @throws

  when behavior depends on error handling.
• Add

  @example

  only when it clarifies non-obvious usage.
• Do not restate TypeScript types in prose unless it adds semantic meaning.

TSDoc Rules

• @param

  for each function argument

• @typeParam

  for generic parameters

• @returns

  for return semantics

• @remarks

  for longer contextual details

• @throws

  for exceptional behavior

• @example

  for practical usage

• @deprecated

  for migration guidance

• Use

  @param name - Description

  with a hyphen separator.
• Prefer inline links with

  {@link SymbolName}

  .
• Keep release tags (

  @alpha

  ,

  @beta

  ,

  @public

  ,

  @internal

  ) aligned with project policy.
• For object parameters in TypeScript, prefer a named

  type

  or

  interface

  and add

  /** ... */

  comments on each property so VS Code hovers/autocomplete show per-property docs.

JSDoc Rules

• @param {Type} name

  (with optional/default forms when needed)

• @returns {Type}

  (or

  @return

  )

• @throws {Type}

  when known

• @typedef

  and

  @property

  for reusable object shapes

• @example

  for usage snippets

• @async

  and

  @yields

  for async/generator behavior when needed

• Optional params:

  @param {string} [name]

• Optional with default:

  @param {string} [name=John Doe]

• Nested object props:

  @param {Object} options

  and

  @param {string} options.mode

JSDoc Consistency Standard

• Keep

  @access

  usage consistent per block (

  @access <level>

  or one shorthand access tag).
• Use

  @implements

  only on classes/constructors.
• Prefer rule-specific guidance from the

  rules/jsdoc/**

  files when there is a conflict.

Output Expectations

• keep existing project conventions unless user requests a migration
• preserve behavior accuracy over verbosity
• avoid adding comments to private/internal symbols unless requested

Additional Reference

Rule Files

• TSDoc index:

  indexes/tsdoc-index.md

• JSDoc authoring index:

  indexes/jsdoc-authoring-index.md

• JSDoc consistency index:

  indexes/jsdoc-consistency-index.md

Full Compiled Document

AGENTS.md