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 ```json { "projectPath": "./packages/babysitter-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 - 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