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

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.

undefinedParameters:undefined

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

undefinedReturns: — Array of extracted JSDoc entries for documented declarations

undefinedExample:undefined

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.", ... }

---

jsdocsToMarkdown

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

Extract JSDoc from TypeScript/JavaScript source and return Markdown.

Convenience wrapper that combines extractJSDocs and renderJSDocsMarkdown.

undefinedParameters:undefined

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

undefinedReturns: — Formatted Markdown documentation string

undefinedExample:undefined

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

---

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.

undefinedParameters:undefined

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

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

undefinedExample:undefined

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

---

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.

undefinedParameters:undefined

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

undefinedReturns: — Parsed description and array of tags

undefinedExample:undefined

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

---

renderJSDocsMarkdown

function renderJSDocsMarkdown(entries: JSDocEntry[], options?: RenderOptions): 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.

undefinedParameters:undefined

• undefinedentries — JSDoc entries to render (from extractJSDocs or loadJSDocs)
• undefinedoptions — Render options (include interfaces)

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

undefinedExample:undefined

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

---

sortEntries

function sortEntries(entries: JSDocEntry[]): JSDocEntry[];

Sort entries alphabetically, with interfaces grouped at the end.

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

local 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.