TSDoc proposes a new format for documenting TypeScript source code. Existing TypeScript API documentation parsers accept a syntax based on JSDoc, but the extensions to JSDoc are inconsistent across implementations.
While JSDoc is the defacto standard for documenting JavaScript source code, according to the TSDoc project, it does not meet the needs of TypeScript documentation on its own:
Unfortunately, the JSDoc grammar is not rigorously specified but instead 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.
The TSDoc syntax is in the planning stage, with no official release yet. At this stage, the project is a collaboration between the TypeScript team and developers working on API Extractor, TypeDoc, DocFX, ts-docs-gen, and Ember.js. TypeScript Program Manager Daniel Rosenwasser explained to InfoQ the motivation behind TSDoc:
The TSDoc effort kind of started organically out of a desire to improve the state of documentation generation tools for TypeScript. We'd gotten a lot of interest in that, and several teams had started tackling the problem, but everyone was doing things a little differently. On top of aligning on behavior, I think this is a really great chance for collaboration between documentation tool authors to identify common problems.
The project intends to publish an npm package, @microsoft/tsdoc , with an open source reference implementation of a TSDoc parser.
The TSDoc format states the following goals:
- Design a grammar for TypeScript while extending JSDoc
- Allow Markdown within comments
- A common set of documentation tags
- Extensible mechanism for adding tags
- Interoperable, so custom tags won’t break parsing of non-custom tags and handling Markdown ambiguities
- Cross-referencing between packages and dependencies
- Open standard
Additionally, the TSDoc reference parser also aims to provide:
- Strict and lax modes, with lax attempting to parse existing JSDoc-based grammar
- Bi-directional round-tripping between doc comments and abstract syntax trees
- Self-contained, no dependency on the TypeScript compiler API, allowing the abstract syntax tree for comments to be a simple JavaScript object tree
TypeScript developers should expect that JSDoc type annotations that are redundant with type information already provided by TypeScript be optional with TSDoc.
As TSDoc is in the early stages, the project is looking for interested parties to get involved now to help make TSDoc a useful approach for all TypeScript source code documentation. Contributions are welcome via the TSDoc GitHub project.