Agent skill

jsdoc-tsdoc

JavaScript and TypeScript documentation generation using JSDoc and TSDoc. Parse source code, generate API documentation, validate coverage, and integrate with TypeDoc for comprehensive developer documentation.

View SKILL.md on GitHub Repository
Stars 514
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/a5c-ai/babysitter/tree/main/library/specializations/technical-documentation/skills/jsdoc-tsdoc

Metadata

Additional technical details for this skill

author
babysitter-sdk
version
1.0.0

SKILL.md

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

json
{
  "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

javascript
/**
 * 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('user@example.com', 'password');
 * console.log(result.token);
 *
 * @since 1.0.0
 * @see {@link logout} for ending sessions
 */
async function authenticate(username, password) {
  // Implementation
}

Class Documentation

javascript
/**
 * 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

typescript
/**
 * 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

typescript
/**
 * 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

typescript
/**
 * 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

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

json
{
  "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

json
{
  "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

json
{
  "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

Target Processes

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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

a5c-ai/babysitter

gsd-tools

Central utility skill for GSD operations. Provides config parsing, slug generation, timestamps, path operations, and orchestrates calls to other specialized skills. Acts as the unified entry point that the original gsd-tools.cjs provided via its lib/ modules (commands, config, core, init).

514 31
Explore
a5c-ai/babysitter

model-profile-resolution

Resolve model profile (quality/balanced/budget) at orchestration start and map agents to specific models. Enables cost/quality tradeoffs by selecting appropriate AI models for each agent role.

514 31
Explore
a5c-ai/babysitter

verification-suite

Plan structure validation, phase completeness checks, reference integrity verification, and artifact existence confirmation. Provides the structured verification layer ensuring GSD artifacts are well-formed and complete.

514 31
Explore
a5c-ai/babysitter

state-management

STATE.md reading, writing, and field-level updates. Provides cross-session state persistence via .planning/STATE.md with structured fields for current task, completed phases, blockers, decisions, and quick tasks.

514 31
Explore
a5c-ai/babysitter

git-integration

Git commit patterns, formats, and conventions for GSD methodology. Provides atomic commits per task, structured commit messages, planning file commits, branch management, and milestone tag operations.

514 31
Explore
a5c-ai/babysitter

frontmatter-parsing

YAML frontmatter parsing and manipulation for .planning/ documents. Provides read, write, update, query, and validation operations on frontmatter blocks in GSD markdown artifacts.

514 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results