BT

TSDoc: A TypeScript Source Code Documentation Format

| by Dylan Schiemann Follow 8 Followers on Apr 19, 2018. Estimated reading time: 2 minutes |

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.

Rate this Article

Adoption Stage
Style

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread
Community comments

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Discuss

Login to InfoQ to interact with what matters most to you.


Recover your password...

Follow

Follow your favorite topics and editors

Quick overview of most important highlights in the industry and on the site.

Like

More signal, less noise

Build your own feed by choosing topics you want to read about and editors you want to hear from.

Notifications

Stay up-to-date

Set up your notifications and don't miss out on content that matters to you

BT