# docs.ts **[Source](https://github.com/ubugeeei-prod/ox-content/blob/main/npm/vite-plugin-ox-content/src/docs.ts)** > 6 documented symbols. Read the signatures first, then expand each item for parameters, return types, and examples.
6 symbols 5 functions 1 modules 10 parameters 5 returns 2 examples
## Reference
moduledocsSource Documentation Extraction and Generation This module provides comprehensive tools for extracting JSDoc/TSDoc comm…1 example

Source Documentation Extraction and Generation

This module provides comprehensive tools for extracting JSDoc/TSDoc comments from TypeScript/JavaScript source files and automatically generating Markdown documentation.

Features

  • Automatic Extraction: Parses JSDoc comments from functions, classes, interfaces, and types
  • Flexible Filtering: Include/exclude patterns for selective documentation
  • Markdown Generation: Converts extracted docs to organized Markdown files
  • Navigation Generation: Auto-generates sidebar navigation metadata
  • GitHub Links: Includes clickable links to source code on GitHub

Supported JSDoc Tags

  • @param {type} name - description - Function parameter documentation
  • @returns {type} description - Return value documentation
  • @example - Code examples (multi-line blocks)
  • @private - Mark item as private (excluded from docs if private=false)
  • @default value - Default parameter value
  • Custom tags are preserved in the tags field

Usage Flow

  1. Call extractDocs() to parse source files
  2. Call generateMarkdown() to create Markdown content
  3. Call writeDocs() to write files to output directory
  4. Generated nav.ts can be imported for sidebar navigation

View source

Examples

Example 1
import { extractDocs, generateMarkdown, writeDocs } from './docs';

const docsOptions = {
  enabled: true,
  src: ['./src'],
  out: './docs/api',
  include: ['**\/*.ts'],
  exclude: ['**\/*.test.ts'],
  groupBy: 'file',
  githubUrl: 'https://github.com/user/project',
};

const extracted = await extractDocs(['./src'], docsOptions);
const markdown = generateMarkdown(extracted, docsOptions);
await writeDocs(markdown, './docs/api', extracted, docsOptions);
fnexistingGeneratedAt(outDir: string): string | undefinedKeep docs.json's timestamp stable across regenerations of the same tree.1 paramreturns string | undefined

Keep docs.json's timestamp stable across regenerations of the same tree.

Signature

function existingGeneratedAt(outDir: string): string | undefined

View source

Parameters

  • outDir string

Returns

string | undefined
fnextractDocs(srcDirs: string[], options: ResolvedDocsOptions): Promise<ExtractedDocs[]>Extracts JSDoc documentation from source files in specified directories. This f…2 paramsreturns Promise<ExtractedDocs[]>1 example

Extracts JSDoc documentation from source files in specified directories.

This function recursively searches directories for source files matching the include/exclude patterns, then extracts all documented items (functions, classes, interfaces, types) from those files.

Process

  1. File Discovery: Recursively walks directories, applying filters
  2. File Reading: Loads each matching file's content
  3. JSDoc Extraction: Parses JSDoc comments using the native parser
  4. Declaration Matching: Pairs JSDoc comments with source declarations
  5. Result Collection: Aggregates extracted documentation by file

Include/Exclude Patterns

Patterns support:

  • ** - Match any directory structure
  • * - Match any filename
  • Standard glob patterns (e.g., **\/*.test.ts)

Performance Considerations

  • Uses filesystem I/O which can be slow for large codebases
  • Consider using more specific include patterns to reduce file scanning
  • Results are not cached; call once per build/dev session

Signature

export async function extractDocs(srcDirs: string[], options: ResolvedDocsOptions): Promise<ExtractedDocs[]>

View source

Parameters

  • srcDirs string[]

    Array of source directory paths to scan

  • options ResolvedDocsOptions

    Documentation extraction options (filters, grouping, etc.)

Returns

Promise<ExtractedDocs[]>

Promise resolving to array of extracted documentation by file.
Each ExtractedDocs object contains file path and array of DocEntry items.

Examples

Example 1
const docs = await extractDocs(
  ['./packages/vite-plugin/src'],
  {
    enabled: true,
    src: [],
    out: 'docs',
    include: ['**\/*.ts'],
    exclude: ['**\/*.test.ts', '**\/*.spec.ts'],
    format: 'markdown',
    private: false,
    toc: true,
    groupBy: 'file',
    generateNav: true,
  }
);

// Returns:
// [
//   {
//     file: '/path/to/transform.ts',
//     entries: [
//       { name: 'transformMarkdown', kind: 'function', ... },
//       { name: 'loadNapiBindings', kind: 'function', ... },
//     ]
//   },
//   ...
// ]
fngenerateMarkdown(docs: ExtractedDocs[], options: ResolvedDocsOptions): Record<string, string>Generates Markdown documentation from extracted docs.2 paramsreturns Record<string, string>

Generates Markdown documentation from extracted docs.

Signature

export function generateMarkdown(docs: ExtractedDocs[], options: ResolvedDocsOptions): Record<string, string>

View source

Parameters

Returns

Record<string, string>
fnresolveDocsOptions(options: false): falseResolves docs options with defaults.1 paramreturns false

Resolves docs options with defaults.

Signature

export function resolveDocsOptions(options: false): false

View source

Parameters

  • options false

Returns

false
fnwriteDocs(docs: Record<string, string>, outDir: string, extractedDocs?: ExtractedDocs[], options?: ResolvedDocsOptions): Promise<void>Writes generated documentation to the output directory.4 paramsreturns Promise<void>

Writes generated documentation to the output directory.

Signature

export async function writeDocs(docs: Record<string, string>, outDir: string, extractedDocs?: ExtractedDocs[], options?: ResolvedDocsOptions): Promise<void>

View source

Parameters

Returns

Promise<void>