tsdoc.ts

TSDoc/JSDoc parsing helpers using the TypeScript compiler API.
Provides parseComment for extracting JSDoc/TSDoc from TypeScript nodes.
Primarily designed for build-time code generation but can be used at runtime.
DesignPure 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 supportSupports a subset of standard TSDoc tags:
@param, @returns, @throws, @example, @deprecated, @see, @since, @default, @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.
Uses same format as @param: @mutates key - description of mutation. The key is
unvalidated — typically a parameter name, but compound paths (this.foo, obj.field)
and external state references are accepted as-is.
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 notesDue to TS Compiler API limitations:
- TS API includes dash separator in @param tag text; we strip the leading -  as it's syntax, not content
- @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
@see declaration-build.ts for DeclarationJsonBuild
@see typescript-exports.ts and svelte.ts as primary consumers

Declarations
#

5 declarations

view source

applyToDeclaration
#

tsdoc.ts view source

(declaration: MemberJsonBuild | DeclarationJsonBuild, 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 MemberJsonBuild | DeclarationJsonBuild

`tsdoc`

parsed TSDoc comment (if available)

type TsdocParsedComment | undefined

returns

void

cleanComment
#

tsdoc.ts view source

(commentText: string): string | undefined

Clean raw JSDoc comment text by removing comment markers and leading asterisks.
Transforms /** ... *\/ style comments into clean text.

`commentText`

the raw comment text including /** and *\/ markers

type string

returns

string | undefined

cleaned comment text, or undefined if empty after cleaning

examples

cleanComment('/** Hello world *\/') // => 'Hello world'
cleanComment('/**\n * Line 1\n * Line 2\n *\/') // => 'Line 1\nLine 2'

hasModuleTag
#

tsdoc.ts view source

(node: Node): boolean

Check if a TypeScript node has a @module JSDoc tag.
Used to prevent @module comments from leaking into declaration docComment fields.
Module-level comments are extracted separately by extractModuleComment.

`node`

the TypeScript node to check

type Node

returns

boolean

true if any JSDoc tag on the node is @module

parseComment
#

tsdoc.ts view source

(node: Node, sourceFile: 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
- @default - default value
- @mutates - mutation documentation (non-standard)
- @nodocs - exclusion flag (non-standard)

`node`

the TypeScript node to extract JSDoc from

type Node

`sourceFile`

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

type SourceFile

returns

TsdocParsedComment | undefined

parsed comment with structured metadata, or undefined if no JSDoc found

examples

const tsdoc = parseComment(declarationNode, sourceFile);
if (tsdoc) {
  console.log(tsdoc.text); // main comment text
  console.log(tsdoc.params); // {paramName: 'description'}
}

TsdocParsedComment
#

tsdoc.ts view source

TsdocParsedComment

Parsed JSDoc/TSDoc comment with structured metadata.
Returned by parseComment — consumers typically pass this to applyToDeclaration
to populate DeclarationJsonBuild fields.

`text`

Comment text (excluding comment markers).

type string

`params`

Parameter descriptions mapped by parameter name.

type Record<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>

`deprecatedMessage`

Deprecation message from @deprecated.

type string

`seeAlso`

Related references from @see.

type Array<string>

`since`

Version information from @since.

type string

`defaultValue`

Default value from @default tag.

type string

`mutates`

Mutation documentation from @mutates (non-standard), mapped by parameter name.

type Record<string, string>

`nodocs`

Whether to exclude from documentation. From @nodocs tag.

type boolean