How to use AI to generate JSDoc and TypeDoc comments for a JavaScript or TypeScript codebase

What this does

This guide describes a workflow for using an AI assistant to generate JSDoc (for JavaScript) or TypeDoc (for TypeScript) comment blocks on functions, classes, interfaces, and modules. Proper documentation comments improve IDE autocomplete, enable documentation generation, and make the codebase easier to onboard new contributors to.

Steps

1. Identify the files or functions that lack documentation. A quick scan using grep -r "@param\|@returns" src/ can reveal undocumented functions.
2. Open the target file in the editor or prepare a batch selection of files.
3. Issue a targeted instruction to the AI assistant: "Add JSDoc comments to all exported functions in this file. Include @param, @returns, and @throws where applicable."
4. Review the proposed comment blocks. Verify they accurately describe parameter types, return types, and side effects by cross-referencing the function implementation.
5. Correct any inaccurate type annotations in the AI-generated comments before accepting.
6. Accept the changes and move to the next file.
7. Run TypeDoc to generate HTML documentation: npx typedoc src/ --out docs/api.
8. Verify the generated documentation renders correctly by checking a sample page in the output directory.

Verification

npx typedoc src/utils/validator.ts --out /tmp/docs-check && ls /tmp/docs-check/index.html
# Expected output: /tmp/docs-check/index.html

Common failures

1. Inaccurate type annotations in comments: The AI infers a wrong type from the function name or context. For example, annotating a parameter as string when the code actually expects a number. Solution: always cross-check AI-generated types against the TypeScript type definitions or runtime behavior.
2. Missing @throws documentation for error paths: The AI documents the happy path but omits possible exceptions. Solution: explicitly ask the AI to "document all error conditions and exceptions" and review the function body for try/catch blocks and thrown errors.
3. Stale comments after refactoring: AI-generated comments become outdated when the function signature or behavior changes. Solution: treat documentation as a separate review step; run a linter that flags mismatched JSDoc types against actual signatures (e.g., ts-check in TypeScript).
4. Overly verbose comments: The AI generates wall-of-text descriptions that hurt readability. Solution: instruct the AI to keep comments concise: one line per parameter, one line for returns.

Related guides

• How to generate README documentation for a repository using an AI tool trained on Markdown
• How to write YAML or OpenAPI spec documentation for your REST API using an AI assistant