**TSDoc** is a proposal to standardize the doc comments used in [TypeScript](http://www.typescriptlang.org/) 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:
We are developing a library package [@microsoft/tsdoc](https://www.npmjs.com/package/@microsoft/tsdoc) that provides an open source reference implementation of a parser. Using this library is an easy way to ensure that your tool is 100% compatible with the standard.
👋***Give it a try!** The <atarget="_blank"href="https://microsoft.github.io/tsdoc/">TSDoc Playground</a> provides an interactive showcase of our parser!*
- [Visual Studio Code](https://code.visualstudio.com): an editor that supports syntax highlighting and interactive refactoring for TypeScript doc comments
- [TypeDoc](https://github.com/TypeStrong/typedoc): an API reference website generator that extracts its content from doc comments
- [DocFX](https://dotnet.github.io/docfx/): an integrated pipeline that ingests API reference content for many different programming languages, but then applies its own Markdown renderer and custom tag parsing
- [API Extractor](https://aka.ms/extractor): a build tool that tracks TypeScript API review workflows and generates *.d.ts rollups for third-party SDKs
These are just examples. Many other tools in today's web developer community want to interact with TypeScript doc comments. Each of these tools accepts a syntax that is loosely based on [JSDoc](http://usejsdoc.org), but encounters frustrating incompatibilities when attempting to coexist with other parsers.
*Why can't JSDoc be the standard?* Unfortunately the JSDoc grammar is not rigorously specified, but rather inferred from the behavior of a particular implementation. The majority of the standard JSDoc tags are preoccupied with providing type annotations for plain JavaScript, which is an irrelevant concern for a strongly-typed language such as TypeScript. **TSDoc** addresses these limitations while also tackling a more sophisticated set of goals.
- **Markdown integration**: Doc comments may incorporate [CommonMark](http://commonmark.org) notations for rich text elements such as boldface, code fences, headings, tables, etc. (This turned out to be the toughest requirement, since the Markdown grammar is very irregular and very dependent on context.) TSDoc makes special accommodations for entrenched pipelines (e.g. GitHub Pages) that expect to bring their own Markdown renderer to the party.
- **Interoperable**: The TSDoc standard guarantees that unsupported custom tags won't interfere with parsing of other content. TSDoc also eliminates Markdown ambiguities. (Are backticks allowed inside a `{@link}` tag? What happens if there is only one backtick? etc.)
- **Multi-package support**: Many teams ship a collection of NPM packages that work together and are documented as a set. The cross-referencing syntax (e.g. `{@link}` or `{@inheritDoc}`) needs a portable way to reference API items imported from other packages. We also define *package.json* metadata that enables tooling to detect whether a dependency's *.d.ts doc comments should be parsed as TSDoc or not.
The **@microsoft/tsdoc** library package brings in some additional goals:
- **"Strict" and "Lax" modes**: Many projects don’t have the time/desire to change their existing code, so they want a "*lax*" mode that makes a best attempt to render their doc comments as-is. Other projects want a "*strict*" mode that ensures consistent syntax everywhere and catches typos that might result in rendering errors. Some projects want to be "*strict*" eventually, but they can't migrate everything overnight; they need a "*transitional*" mode similar to tslint suppressions.
- **Comment-emitter for roundtripping**: The parser reads doc comments as input and produces an abstract syntax tree (AST) as output. This should be reversible: given an AST input (possibly with modifications), the library can regenerate the corresponding doc comment.
- **Self-contained**: The implementation will be small, fast, and self-contained. It will not have a dependency on the TypeScript compiler API. Doc comments will be received as a plain text string, and the AST will be a simple JavaScript tree object. This makes it easier for tools to accept **@microsoft/tsdoc** as a dependency.
NOTE: The **@microsoft/tsdoc** library is intended to be incorporated into other build tools that analyze TypeScript source code, such as the projects linked below. (By itself, the TSDoc library is not a documentation tool that you can use directly.)
- Check out the [TSDoc Playground](https://microsoft.github.io/tsdoc/) for a cool interactive demo of TSDoc! :-)
- The library [@microsoft/tsdoc](https://www.npmjs.com/package/@microsoft/tsdoc) provides a TSDoc parser that you can use in your own projects. The source code for this library can be found in the [/tsdoc](./tsdoc/) folder.
- We also provide an ESLint plugin [eslint-plugin-tsdoc](https://www.npmjs.com/package/eslint-plugin-tsdoc) that you can use to validate your source code.
- We're using [GitHub issues](https://github.com/Microsoft/tsdoc/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) to discuss the TSDoc specification, library design, and project roadmap.
- [Tom Dale](https://github.com/tomdale), who's working on the documentation engine for [Ember.js](https://www.emberjs.com), [Glimmer.js](https://glimmerjs.com), and other projects
- Convert Microsoft's API Extractor tool to use **@microsoft/tsdoc** (replacing its proprietary AEDoc engine); this demonstrates that TSDoc can meet the needs of [a large production documentation web site](https://docs.microsoft.com/en-us/javascript/api/sp-core-library?view=sp-typescript-latest)
