a5c-ai/jsdoc-tsdoc

JSDoc/TSDoc Skill

Generate and validate JavaScript and TypeScript documentation using industry-standard JSDoc and TSDoc conventions with TypeDoc integration.

Capabilities

• Parse JSDoc comments from JavaScript source code
• Parse TSDoc comments from TypeScript source code
• Generate API documentation with TypeDoc
• Validate documentation coverage and completeness
• Enforce documentation standards with ESLint plugins
• Support custom JSDoc/TSDoc tags
• Type inference and documentation alignment
• Generate multiple output formats (HTML, Markdown, JSON)

Usage

Invoke this skill when you need to:

• Document JavaScript/TypeScript libraries and APIs
• Generate API reference documentation
• Audit documentation coverage
• Set up automated documentation pipelines
• Validate doc comments match implementation

Inputs

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | projectPath | string | Yes | Root path of the JS/TS project | | entryPoints | array | No | Specific files/directories to document | | outputDir | string | No | Documentation output directory (default: docs) | | outputFormat | string | No | html, markdown, json (default: html) | | includePrivate | boolean | No | Include private members (default: false) | | coverageThreshold | number | No | Minimum documentation coverage % | | customTags | array | No | Additional JSDoc/TSDoc tags to recognize |

Input Example

{
  "projectPath": "./packages/sdk",
  "entryPoints": ["src/index.ts", "src/client.ts"],
  "outputDir": "docs/api",
  "outputFormat": "html",
  "coverageThreshold": 80,
  "customTags": ["@alpha", "@beta", "@experimental"]
}

Output Structure

docs/api/
├── index.html           # Documentation home
├── modules.html         # Module index
├── classes/
│   ├── Client.html      # Class documentation
│   └── Config.html
├── interfaces/
│   ├── Options.html     # Interface documentation
│   └── Response.html
├── functions/
│   └── helpers.html     # Function documentation
├── types/
│   └── aliases.html     # Type alias documentation
├── assets/
│   ├── main.js
│   └── style.css
└── coverage.json        # Documentation coverage report

JSDoc Comment Patterns

Function Documentation

/**
 * Authenticates a user with the API.
 *
 * @param {string} username - The user's username
 * @param {string} password - The user's password
 * @returns {Promise<AuthResult>} Authentication result with token
 * @throws {AuthError} When credentials are invalid
 * @example
 * const result = await authenticate('[email protected]', 'password');
 * console.log(result.token);
 *
 * @since 1.0.0
 * @see {@link logout} for ending sessions
 */
async function authenticate(username, password) {
  // Implementation
}

Class Documentation

/**
 * HTTP client for API communication.
 *
 * @class
 * @extends EventEmitter
 * @implements {Disposable}
 *
 * @example
 * const client = new ApiClient({ baseUrl: 'https://api.example.com' });
 * const response = await client.get('/users');
 */
class ApiClient extends EventEmitter {
  /**
   * Creates a new API client instance.
   *
   * @param {ClientOptions} options - Client configuration
   * @param {string} options.baseUrl - Base URL for API requests
   * @param {number} [options.timeout=30000] - Request timeout in ms
   */
  constructor(options) {
    // Implementation
  }

  /**
   * Performs a GET request.
   *
   * @param {string} path - Request path
   * @param {RequestOptions} [options] - Additional options
   * @returns {Promise<Response>} The response
   */
  async get(path, options) {
    // Implementation
  }
}

TSDoc Comment Patterns

Package Documentation

/**
 * SDK for interacting with the Example API.
 *
 * @remarks
 * This package provides a type-safe client for the Example API.
 * It supports both browser and Node.js environments.
 *
 * @packageDocumentation
 */

Function with Overloads

/**
 * Fetches data from the API.
 *
 * @param url - The endpoint URL
 * @returns The response data
 *
 * @example
 * ```typescript
 * const users = await fetch<User[]>('/api/users');
 * ```
 *
 * @public
 */
export async function fetch<T>(url: string): Promise<T>;

/**
 * Fetches data with custom options.
 *
 * @param url - The endpoint URL
 * @param options - Request options
 * @returns The response data
 *
 * @public
 */
export async function fetch<T>(url: string, options: FetchOptions): Promise<T>;

Interface Documentation

/**
 * Configuration options for the API client.
 *
 * @remarks
 * All timeout values are in milliseconds.
 *
 * @example
 * ```typescript
 * const config: ClientConfig = {
 *   baseUrl: 'https://api.example.com',
 *   timeout: 5000,
 *   retries: 3
 * };
 * ```
 *
 * @public
 */
export interface ClientConfig {
  /**
   * Base URL for all API requests.
   * @remarks Must include protocol (https://)
   */
  baseUrl: string;

  /**
   * Request timeout in milliseconds.
   * @defaultValue 30000
   */
  timeout?: number;

  /**
   * Number of retry attempts for failed requests.
   * @defaultValue 0
   */
  retries?: number;

  /**
   * Custom headers to include with every request.
   * @beta
   */
  headers?: Record<string, string>;
}

TypeDoc Configuration

typedoc.json

{
  "$schema": "https://typedoc.org/schema.json",
  "entryPoints": ["src/index.ts"],
  "out": "docs/api",
  "name": "My SDK",
  "readme": "README.md",
  "includeVersion": true,
  "excludePrivate": true,
  "excludeProtected": false,
  "excludeInternal": true,
  "excludeExternals": true,
  "categorizeByGroup": true,
  "categoryOrder": [
    "Client",
    "Configuration",
    "Types",
    "Utilities",
    "*"
  ],
  "navigation": {
    "includeCategories": true,
    "includeGroups": true
  },
  "plugin": [
    "typedoc-plugin-markdown"
  ],
  "theme": "default",
  "validation": {
    "notExported": true,
    "invalidLink": true,
    "notDocumented": false
  }
}

ESLint Documentation Rules

{
  "plugins": ["jsdoc"],
  "extends": ["plugin:jsdoc/recommended-typescript"],
  "rules": {
    "jsdoc/require-jsdoc": ["warn", {
      "require": {
        "FunctionDeclaration": true,
        "MethodDefinition": true,
        "ClassDeclaration": true,
        "ArrowFunctionExpression": false
      },
      "publicOnly": true
    }],
    "jsdoc/require-description": "warn",
    "jsdoc/require-param-description": "warn",
    "jsdoc/require-returns-description": "warn",
    "jsdoc/check-tag-names": ["error", {
      "definedTags": ["alpha", "beta", "experimental", "internal"]
    }],
    "jsdoc/check-types": "error",
    "jsdoc/no-undefined-types": "error",
    "jsdoc/valid-types": "error"
  }
}

Coverage Analysis

Coverage Report Format

{
  "summary": {
    "documented": 145,
    "undocumented": 23,
    "total": 168,
    "percentage": 86.31
  },
  "byKind": {
    "class": { "documented": 12, "total": 14 },
    "interface": { "documented": 28, "total": 30 },
    "function": { "documented": 45, "total": 52 },
    "method": { "documented": 60, "total": 72 }
  },
  "undocumented": [
    {
      "name": "internalHelper",
      "kind": "function",
      "file": "src/utils/helpers.ts",
      "line": 42
    }
  ],
  "incomplete": [
    {
      "name": "processData",
      "kind": "function",
      "file": "src/core/processor.ts",
      "issues": ["missing @returns", "missing @param for 'options'"]
    }
  ]
}

Workflow

1. Analyze project - Scan for TypeScript/JavaScript files
2. Parse documentation - Extract JSDoc/TSDoc comments
3. Validate coverage - Check against threshold
4. Type alignment - Verify docs match TypeScript types
5. Generate documentation - Run TypeDoc or JSDoc
6. Create coverage report - Output coverage analysis
7. Lint validation - Run ESLint documentation rules

Dependencies

{
  "devDependencies": {
    "typedoc": "^0.25.0",
    "typedoc-plugin-markdown": "^4.0.0",
    "eslint-plugin-jsdoc": "^48.0.0",
    "@microsoft/tsdoc": "^0.14.0",
    "@microsoft/tsdoc-config": "^0.16.0"
  }
}

Best Practices Applied

• TSDoc for TypeScript, JSDoc for JavaScript
• Always document public API surface
• Include @example for complex functions
• Use @remarks for implementation notes
• Link related symbols with @see
• Mark experimental features with @alpha/@beta
• Validate types match documentation

References

• TypeDoc: https://typedoc.org/
• TSDoc: https://tsdoc.org/
• JSDoc: https://jsdoc.app/
• eslint-plugin-jsdoc: https://github.com/gajus/eslint-plugin-jsdoc

Target Processes

• api-doc-generation.js
• sdk-doc-generation.js
• docs-audit.js
• docs-testing.js