microsoft/tsdoc: a doc comment standard and parser for TypeScript

What microsoft/tsdoc actually is, and who it is for

The repository describes itself as a doc comment standard for TypeScript. That phrasing matters, because the project is not a documentation tool in the sense most people mean. It is a specification plus the machinery to enforce and parse that specification. The monorepo splits into four published or local pieces: the @microsoft/tsdoc parser library, the @microsoft/tsdoc-config loader for tsdoc.json, the eslint-plugin-tsdoc plugin, and local projects for the API demo and the TSDoc Playground web app. A spec/ folder and a rush.json file sit at the top level, so the build is managed by Rush rather than by a single package.json at the root.

The audience follows from that layout. If you maintain a compiler, a linter, an editor extension or a documentation pipeline that has to read doc comments out of TypeScript source, you need a parser that agrees with other tools about what `@param`, `@remarks` and the rest mean. TSDoc is an attempt to fix that grammar. If you simply want a rendered API reference site for your library, this repository will not give you one, and the README points to a tag reference and a playground rather than to a generator.

The standard exists because JSDoc syntax grew by accretion across many tools, and each tool interpreted ambiguous constructs differently. TSDoc narrows the grammar so a parser can be strict. That strictness is the product.

How the parser and tsdoc.json fit together

The architecture visible in the repository is a pipeline of small packages. @microsoft/tsdoc is the parser library. It takes comment text and produces a structured syntax tree of tags, blocks and inline elements. @microsoft/tsdoc-config loads a tsdoc.json file, which is where a project declares which tags it supports and how they are grouped. The eslint-plugin-tsdoc sits on top of both and reports parser diagnostics as lint errors inside ESLint.

The separation is deliberate. The parser does not know your project's tag vocabulary; tsdoc.json supplies it. That means a tool author can accept custom tags without forking the parser, and a project can keep its own tag set without waiting for the standard to absorb it. The README links a TSDoc tag reference covering syntax elements such as `@param` and `@remarks`, and a TSDoc Playground that the README calls an interactive demo of the parser engine. The playground is useful for checking how a given comment parses before you wire the parser into anything.

One consequence worth stating plainly: because tsdoc-config exists as a separate loader, the configuration is not implicit. A tool that consumes the parser has to decide whether to read tsdoc.json, and the repository gives you the loader rather than a convention that applies itself.

Installing @microsoft/tsdoc and parsing a first comment

The packages are published to npm under the @microsoft scope, as shown by the version badges in the README table. The parser library is @microsoft/tsdoc, and the README links its npm page. It does not print an install command, so the only thing to copy from the repository is the package name itself:

npm install @microsoft/tsdoc

The README points to the api-demo folder as the place where code samples illustrate how to use the parser, so that folder is the reference for a working example rather than the README itself. The general shape is that you construct a configuration, hand it to the parser, and read the resulting document back. The playground at tsdoc.org/play is the fastest way to see what the parser produces for a given comment before writing code against it.

If your goal is enforcement rather than custom tooling, the ESLint plugin is the shorter path. The README lists it as eslint-plugin-tsdoc, published on npm, and the plugin reports TSDoc syntax problems through ESLint's normal diagnostic channel:

npm install eslint-plugin-tsdoc

After installing, the plugin has to be registered in your ESLint configuration and its rule enabled, which is ESLint configuration work rather than something the README spells out. Treat the plugin as the entry point for teams who only want malformed comments flagged in CI, and the parser as the entry point for anyone building on top.

Where TSDoc stops and TypeDoc begins

The most common confusion around this project is the difference between TSDoc and TypeDoc, and the repository does not resolve it for you. TSDoc is a comment syntax and a parser for that syntax. TypeDoc is a documentation generator: it walks a TypeScript project and emits a website or Markdown from your types and comments. They operate at different layers. A generator needs a parser to understand the comments it renders, and TSDoc is a candidate for that job.

So the honest comparison is not TSDoc against TypeDoc as rivals. It is TSDoc against JSDoc, the older and looser convention that most TypeScript tooling still accepts. JSDoc's grammar accumulated across many tools and permits constructs that are ambiguous to parse. TSDoc trades that tolerance for a stricter grammar, which is why a parser can be confident about what it read. The cost is that TSDoc is not a drop-in replacement for every JSDoc comment you have already written, and the repository's spec folder is where the exact rules live rather than the README.

If your existing comments are JSDoc and your generator already handles them, switching buys you parseability and costs you a migration. If you are writing a new tool that consumes comments, starting from a strict grammar avoids inheriting JSDoc's ambiguities.

The limits: no renderer, a separate config loader, and a spec you have to read

The clearest limitation is that the repository ships no documentation site generator. Nothing in the README, the project table or the top-level entries describes one. If you install @microsoft/tsdoc expecting an output artifact, you will get a syntax tree and a set of diagnostics instead, and you will still need to write the rendering step or pair the parser with a generator that already understands TSDoc.

The second limit is configuration. Because @microsoft/tsdoc-config is a distinct package, a tool that uses the parser is not automatically governed by your tsdoc.json. Adoption therefore involves a decision about who reads the config and when, and that decision is not made for you by installing the parser.

The third is scope of the standard itself. The README links the tag reference at an alpha URL, which is a signal about maturity of the tag set rather than a promise of stability. A project that depends on a tag not yet covered by the reference is relying on something the specification may still be settling. That is not a defect in the repository; it is a reason to check the tag reference before designing a comment convention around a particular tag.

Finally, the repository is a Rush monorepo. Contributing means building through the Rush tooling described in the contributing pages, not running a single install at the root. That raises the cost of patching the parser locally if you need a behaviour the maintainers have not shipped.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-18, so work is recent. There are no release notes in the repository listing, so version history has to be read from the per-package CHANGELOG.md files linked in the README table: one for eslint-plugin-tsdoc, one for @microsoft/tsdoc, and one for @microsoft/tsdoc-config. Those changelogs are the practical upgrade reference, since the packages version independently.

Licensing is MIT, which is permissive and imposes no obligation to publish modifications. The README adds a contributor side that does not affect consumers: contributions generally require agreeing to a Contributor License Agreement, with a CLA bot checking pull requests, and the project follows the Microsoft Open Source Code of Conduct. Those terms bind people submitting code, not teams depending on the published packages.

The upgrade cost is concentrated in two places. Parser behaviour changes can alter diagnostics, which means an ESLint rule that passed yesterday can fail today after a minor bump. Tag vocabulary changes interact with your tsdoc.json, since a tag you declared may be reclassified. Reading the relevant CHANGELOG.md before bumping is cheaper than discovering either in CI.

Editorial conclusion

Adopt microsoft/tsdoc if you are building a tool that reads or validates doc comments in TypeScript, or if you want ESLint to flag malformed ones via eslint-plugin-tsdoc. Do not adopt it expecting a documentation website: the repository contains a parser, a config loader, an ESLint plugin, a spec and a playground, and no site generator. Before committing, read the tag reference at tsdoc.org/pages/tags/alpha/ to check that the tags you rely on are defined, and inspect the tsdoc/ and tsdoc-config/ folders to see the exact packages you would pull in.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. microsoft/tsdoc on GitHub
4. Project website
5. README