@microsoft/tsdoc, jsdoc, and typedoc are all related to generating or processing code documentation, but they serve distinct roles in the JavaScript/TypeScript ecosystem. @microsoft/tsdoc is a parser and specification for TypeScript doc comments, providing a standardized syntax (TSDoc) that tools can reliably consume. jsdoc is a long-standing documentation generator originally designed for JavaScript, which parses JSDoc-style comments to produce human-readable documentation in various formats, though it has limited native understanding of TypeScript. typedoc is a TypeScript-first documentation generator that leverages the TypeScript compiler to produce rich API documentation from TSDoc-style comments, offering deep integration with type information and modern output capabilities.
TypeScript Documentation Tools: @microsoft/tsdoc vs JSDoc vs TypeDoc
When building large-scale TypeScript applications, clear and maintainable documentation is essential—not just for external consumers but also for internal team collaboration. The ecosystem offers three main tools in this space: @microsoft/tsdoc, jsdoc, and typedoc. While they all relate to code documentation, they serve fundamentally different roles in the toolchain. Let’s break down how they differ and where each fits.
📝 Core Purpose: Parser vs Generator vs Standard
@microsoft/tsdoc is not a documentation generator—it’s a parser and standard for TypeScript doc comments. It defines a formal syntax (TSDoc) that tools can consume reliably. Think of it as the "specification" layer.
// TSDoc comment parsed by @microsoft/tsdoc
/**
* Adds two numbers together.
* @param a - The first number
* @param b - The second number
* @returns The sum of a and b
*/
function add(a: number, b: number): number {
return a + b;
}
jsdoc is a documentation generator originally built for JavaScript. It parses JSDoc-style comments and outputs HTML, Markdown, or other formats. It has limited understanding of TypeScript types and requires plugins or workarounds for full TS support.
// JSDoc comment (JavaScript-focused)
/**
* Adds two numbers together.
* @param {number} a - The first number
* @param {number} b - The second number
* @returns {number} The sum of a and b
*/
function add(a, b) {
return a + b;
}
typedoc is a TypeScript-first documentation generator. It reads your .ts files, understands your types natively, and generates rich API documentation using TSDoc-style comments. It uses @microsoft/tsdoc under the hood to parse comments.
// TypeDoc consumes TSDoc comments with full type awareness
/**
* Represents a user in the system.
*/
interface User {
/** Unique identifier */
id: string;
/** Full name of the user */
name: string;
}
🔍 Type Awareness: From Ignorant to Native
@microsoft/tsdoc doesn’t generate docs—it just parses comments into a structured AST. It assumes you’re working in a TypeScript context, so it expects TSDoc syntax but doesn’t validate against actual types.
// Valid TSDoc syntax, but no type checking
/**
* @param x - This param isn't even in the function!
*/
function foo() {}
// tsdoc won't complain — that's up to linters or TypeDoc
jsdoc treats TypeScript as plain JavaScript. Without plugins like jsdoc-tsd, it ignores type annotations entirely and only sees JSDoc tags.
// jsdoc sees this as untyped JavaScript
function greet(name: string): string {
return `Hello, ${name}`;
}
// To get types in jsdoc output, you must duplicate them in JSDoc:
/**
* @param {string} name
* @returns {string}
*/
typedoc leverages the TypeScript compiler directly. It infers types from your code and merges them with TSDoc comments—no duplication needed.
// TypeDoc automatically shows `name: string` and `return: string`
/**
* Greets a user by name.
*/
function greet(name: string): string {
return `Hello, ${name}`;
}
// No need for @param or @returns unless you want custom descriptions
⚙️ Integration and Ecosystem
@microsoft/tsdoc is meant to be embedded in other tools. For example, ESLint plugins like eslint-plugin-tsdoc use it to validate comment syntax. You wouldn’t run it standalone.
// Example: using tsdoc in a custom tool
import { TSDocParser } from '@microsoft/tsdoc';
const parser = new TSDocParser();
const docComment = '/** @param x - value */';
const result = parser.parseString(docComment);
// Now you have a structured object to analyze
jsdoc runs as a CLI tool (npx jsdoc src) and supports templates and plugins. However, its TypeScript support remains bolted-on rather than native.
# Typical jsdoc usage (requires config for TS)
npx jsdoc --configure jsdoc.conf.json src/
typedoc integrates seamlessly with TypeScript projects. Just point it at your tsconfig.json:
# TypeDoc uses your existing tsconfig
npx typedoc --tsconfig tsconfig.json
It also supports themes, custom rendering, and linking to source code on GitHub.
🛠️ When Validation Matters
If you want to enforce consistent doc comment syntax across a large codebase, @microsoft/tsdoc (via linters) is your best bet. It ensures everyone writes @param name – description instead of mixing styles.
// .eslintrc.json
{
"plugins": ["tsdoc"],
"rules": {
"tsdoc/syntax": "error"
}
}
jsdoc has validation via its own rules, but again, it’s not TS-aware. typedoc will warn about mismatched parameters but focuses more on generation than linting.
🌐 Output Capabilities
@microsoft/tsdoc: No output. Pure parsing.
jsdoc: Outputs static sites (HTML), JSON, or Markdown. Themes are customizable but often feel dated.
// jsdoc can output JSON for custom processing
npx jsdoc -X src/ > docs.json
typedoc: Generates modern, searchable HTML docs with navigation, member tables, and inheritance diagrams. Also supports JSON output.
# Generate both HTML and JSON
npx typedoc --out docs/ --json docs.json
🧩 Real-World Workflow Recommendations
Scenario 1: Building an Open-Source TypeScript Library
- ✅ Use
typedocto generate beautiful, type-rich API docs. - ✅ Use
@microsoft/tsdoc(via ESLint) to enforce comment style during development. - ❌ Avoid
jsdoc—it adds noise without leveraging your TS types.
Scenario 2: Maintaining a Legacy JavaScript Codebase
- ✅
jsdocis still the right choice if you’re not using TypeScript. - If you migrate to TS later, switch to TypeDoc.
Scenario 3: Creating a Custom Documentation Tool
- ✅ Use
@microsoft/tsdocas your parser to ensure compatibility with the TSDoc standard. - Combine with TypeScript Compiler API for type-aware analysis.
📊 Summary Table
| Feature | @microsoft/tsdoc | jsdoc | typedoc |
|---|---|---|---|
| Primary Role | Comment parser / spec | JS doc generator | TS doc generator |
| TypeScript Support | Syntax only (no types) | Limited (needs plugins) | Native (uses TS compiler) |
| Generates Docs? | ❌ No | ✅ Yes | ✅ Yes |
| CLI Tool? | ❌ No | ✅ Yes | ✅ Yes |
| Best For | Linting, tool integration | Legacy JS projects | Modern TS libraries |
💡 Final Guidance
Don’t think of these as direct competitors—they’re layers in a stack:
@microsoft/tsdocdefines how to write comments.typedocuses that standard to generate docs from TypeScript code.jsdocis a legacy option for non-TypeScript projects.
For any serious TypeScript project today, the combo of TSDoc syntax + TypeDoc generation + tsdoc linting gives you the most maintainable, scalable documentation workflow.
- @microsoft/tsdoc:
Choose
@microsoft/tsdocwhen you need to enforce or parse TSDoc comment syntax programmatically—such as building linters, custom documentation tools, or IDE integrations. It’s not a documentation generator, so avoid it if your goal is to produce end-user docs; instead, use it as a foundational layer for tooling that requires standardized comment parsing in TypeScript projects. - typedoc:
Choose
typedocfor any modern TypeScript project where you need to generate comprehensive, type-aware API documentation. It automatically infers types from your code, supports TSDoc syntax, and produces clean, navigable HTML output with minimal configuration. It’s the go-to solution for open-source libraries, internal SDKs, or any codebase where accurate, up-to-date documentation is critical. - jsdoc:
Choose
jsdoconly if you’re working on a legacy JavaScript codebase without TypeScript, or if you have heavy investment in JSDoc conventions and templates that can’t be migrated. Avoid it for new TypeScript projects, as it lacks native type awareness and requires redundant type annotations in comments, leading to maintenance overhead and potential inconsistencies.
@microsoft/tsdoc
This library is the reference implementation of a parser for the TSDoc syntax. Using this library is an easy way to ensure that your tool is 100% compatible with the standard.
What is TSDoc?
TSDoc is a proposal to standardize the doc comments used in TypeScript source files. It allows different tools to extract content from comments without getting confused by each other's syntax. The TSDoc notation looks pretty familiar:
export class Statistics {
/**
* Returns the average of two numbers.
*
* @remarks
* This method is part of the {@link core-library#Statistics | Statistics subsystem}.
*
* @param x - The first input number
* @param y - The second input number
* @returns The arithmetic mean of `x` and `y`
*
* @beta
*/
public static getAverage(x: number, y: number): number {
return (x + y) / 2.0;
}
}
Give it a try!
Check out the TSDoc Playground for a cool live demo of our parser!
API Usage
The api-demo folder on GitHub illustrates how to invoke the TSDoc parser.
A separate NPM package @microsoft/tsdoc-config
is used for loading the tsdoc.json file.
Get involved
The TSDoc project is actively evolving. Please visit the website for the latest documentation, instructions for building/debugging the projects, and other resources: