tsdoc_helpers.ts

Declarations
#

TSDoc/JSDoc parsing helpers using the TypeScript Compiler API.
Provides tsdoc_parse() for extracting JSDoc/TSDoc from TypeScript nodes. Primarily designed for build-time code generation but can be used at runtime.
Design
Pure extraction approach: extracts documentation as-is with minimal transformation, preserving source intent. Works around TypeScript Compiler API quirks where needed.
Supports both regular TypeScript and Svelte components (via svelte2tsx output).
Tag support
Supports a subset of standard TSDoc tags: @param, @returns, @throws, @example, @deprecated, @see, @since, @nodocs.
The @nodocs tag excludes exports from documentation and flat namespace validation. The declaration is still exported and usable, just not documented.
Also supports @mutates (non-standard) for documenting mutations to parameters or external state. Use format: @mutates paramName - description of mutation.
Only @returns is supported (not @return).
The @see tag supports multiple formats: plain URLs (https://...), {@link} syntax, and module names. Relative/absolute path support in @see is TBD.
Behavioral notes
Due to TS Compiler API limitations: - Preserves dash separator in @param descriptions: @param x desc → "- desc" - @throws tags have {Type} stripped by TS API; fallback regex extracts first word as error type - TS API strips URL protocols from @see tag text; we use getText() to preserve original format including {@link} syntax
All functions are prefixed with tsdoc_ for clarity.

3 declarations

view source

tsdoc_apply_to_declaration
#

tsdoc_helpers.ts view source

(declaration: { [x: string]: unknown; name: string; kind: "function" | "type" | "json" | "variable" | "class" | "constructor" | "component" | "css"; doc_comment?: string | undefined; type_signature?: string | undefined; ... 17 more ...; alias_of?: { ...; } | undefined; }, tsdoc: TsdocParsedComment | undefined): void

Apply parsed TSDoc metadata to a declaration.

Consolidates the common pattern of assigning TSDoc fields to declarations, with conditional assignment for array fields (only if non-empty).

`declaration`

declaration object to update

type

{ [x: string]: unknown; name: string; kind: "function" | "type" | "json" | "variable" | "class" | "constructor" | "component" | "css"; doc_comment?: string | undefined; type_signature?: string | undefined; ... 17 more ...; alias_of?: { ...; } | undefined; }

`tsdoc`

parsed TSDoc comment (if available)

type TsdocParsedComment | undefined

returns

void

tsdoc_parse
#

tsdoc_helpers.ts view source

(node: Node, source_file: SourceFile): TsdocParsedComment | undefined

Parse JSDoc comment from a TypeScript node.

Extracts and parses all JSDoc tags including:

- @param - parameter descriptions - @returns - return value description - @throws - error documentation - @example - code examples - @deprecated - deprecation warnings - @see - related references - @since - version information - @mutates - mutation documentation (non-standard)

`node`

The TypeScript node to extract JSDoc from

type Node

`source_file`

Source file (used for extracting full @see tag text)

type SourceFile

returns

TsdocParsedComment | undefined

TsdocParsedComment
#

tsdoc_helpers.ts view source

TsdocParsedComment

Parsed JSDoc/TSDoc comment with structured metadata.

`text`

Comment text (excluding comment markers)

type string

`params`

Parameter descriptions mapped by parameter name

type Map<string, string>

`returns`

Return value description from @returns

type string

`throws`

Thrown errors from @throws

type Array<{type?: string; description: string}>

`examples`

Code examples from @example

type Array<string>

`deprecated_message`

Deprecation message from @deprecated

type string

`see_also`

Related references from @see

type Array<string>

`since`

Version information from @since

type string

`mutates`

Mutation documentation from @mutates (non-standard)

type Array<string>

`nodocs`

Whether to exclude from documentation. From @nodocs tag.

type boolean