docs4ts

Extract JSDoc documentation from TypeScript/JavaScript source files and generate formatted Markdown. Uses oxc-parser for fast, accurate parsing with automatic re-export traversal.

CLI

# Print markdown to stdout
npx docs4ts src/index.ts

# Write to file
npx docs4ts src/index.ts -o docs/api.md

Usage: docs4ts [options] <file>

Options:
  -o, --out <file>  Write output to file
  -h, --help        Show this help

The CLI follows re-exports automatically — point it at your entry file and it will traverse the module graph to document all exported symbols.

Programmatic Usage

JSDocTag

interface JSDocTag

Parsed JSDoc tag (e.g. @param, @returns, @example).

JSDocEntry

interface JSDocEntry

A single documented declaration extracted from source code.

ExtractJSDocsOptions

interface ExtractJSDocsOptions

Options for extractJSDocs.

extractJSDocs

function extractJSDocs(source: string, options?: ExtractJSDocsOptions): JSDocEntry[];

Extract JSDoc entries from TypeScript/JavaScript source code.

Parses the source with oxc-parser, matches JSDoc block comments to their associated declarations by byte position, and returns structured entries.

Parameters:

• source — Source code string to parse
• options — Parser options (filename hint, include private declarations)

Returns: — Array of extracted JSDoc entries for documented declarations

Example:

const entries = extractJSDocs(`
  /** Add two numbers. *​/
  export function add(a: number, b: number): number {
    return a + b;
  }
`);
// entries[0] => { name: "add", kind: "function", description: "Add two numbers.", ... }

parseJSDoc

function parseJSDoc(raw: string):

Parse raw JSDoc comment content into description and tags.

Expects the inner content of a /** ... *​/ block (without the delimiters). Splits the comment into a leading description and structured @tag entries.

Parameters:

• raw — Raw JSDoc comment body (the text between /** and *​/)

Returns: — Parsed description and array of tags

Example:

const { description, tags } = parseJSDoc(`
  * Add two numbers.
  * @param a - First number
  * @param b - Second number
  * @returns The sum
`);

renderJSDocsMarkdown

function renderJSDocsMarkdown(entries: JSDocEntry[]): string;

Render an array of JSDoc entries as formatted Markdown.

Each entry becomes a ### section with signature, description, parameters, return info, examples, and other tags.

Parameters:

• entries — JSDoc entries to render (from extractJSDocs or loadJSDocs)

Returns: — Formatted Markdown string with --- separators between sections

Example:

const entries = await loadJSDocs("src/index.ts");
const markdown = renderJSDocsMarkdown(entries);

jsdocsToMarkdown

function jsdocsToMarkdown(source: string, options?: ExtractJSDocsOptions): string;

Extract JSDoc from TypeScript/JavaScript source and return Markdown.

Convenience wrapper that combines extractJSDocs and renderJSDocsMarkdown.

Parameters:

• source — Source code string to parse
• options — Parser options (filename hint, include private declarations)

Returns: — Formatted Markdown documentation string

Example:

const markdown = jsdocsToMarkdown(`
  /** Greet someone. *​/
  export function greet(name: string): string {
    return "Hello, " + name;
  }
`);

LoadJSDocsOptions

interface LoadJSDocsOptions

Options for loadJSDocs.

loadJSDocs

async function loadJSDocs(entry: string, options?: LoadJSDocsOptions): Promise<JSDocEntry[]>;

Load JSDoc entries from an entry file, traversing all re-exported modules.

Starting from the given file, follows export ... from and export * statements to collect documentation across the entire module graph.

Parameters:

• entry — Path to the entry file to start from
• options — Loader options (include private declarations)

Returns: — Array of JSDoc entries collected from all traversed modules

Example:

const entries = await loadJSDocs("src/index.ts");

Types

interface JSDocEntry {
  kind: "function" | "class" | "interface" | "type" | "enum" | "variable" | "method" | "property";
  name: string;
  exported: boolean;
  description?: string;
  tags: JSDocTag[];
  signature?: string;
}

interface JSDocTag {
  tag: string;
  name?: string;
  type?: string;
  description?: string;
}

Development

• Clone this repository
• Install latest LTS version of Node.js
• Enable Corepack using corepack enable
• Install dependencies using pnpm install
• Run interactive tests using pnpm dev

License

Published under the MIT license.