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.

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, @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 notes

JSDoc blocks tagged @module are excluded from parseComment entirely (text and tags) — module comments attach to the file's first statement in the AST and are owned by extractModuleComment instead.

Due 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

view source

Declarations
#

4 declarations

applyToDeclaration
#

tsdoc.ts view source

(declaration: MemberJsonBuild | DeclarationJsonBuild, tsdoc: TsdocParsedComment | undefined): void import {applyToDeclaration} from 'svelte-docinfo/tsdoc.js';

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

mutates

declaration — adds docComment, deprecatedMessage, examples, seeAlso, throws, since, mutates, defaultValue fields

cleanComment
#

tsdoc.ts view source

(commentText: string): string | undefined import {cleanComment} from 'svelte-docinfo/tsdoc.js';

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'

parseComment
#

tsdoc.ts view source

(node: Node, sourceFile: SourceFile): TsdocParsedComment | undefined import {parseComment} from 'svelte-docinfo/tsdoc.js';

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)

JSDoc blocks tagged @module are excluded entirely (text and tags): a module comment attaches to the file's first statement in the AST, and without the filter it would read as that statement's own docs. extractModuleComment (typescript-exports.ts) owns module comments.

`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 (or only @module blocks)

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 import type {TsdocParsedComment} from 'svelte-docinfo/tsdoc.js';

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

Depends on
#

declaration-build.ts