TSDoc - TypeScriptソースコードのドキュメント化フォーマット

TSDocは、TypeScriptソースコードを文書化するための新たなフォーマットの提案である。既存のTypeScript APIドキュメントパーザはJSDocに基づく構文を受け入れるが、JSDocの拡張部分に関しては実装間で一貫性がなかった。

JSDocはJavaScriptソースコードのドキュメント化のデファクト標準だが、TSDocプロジェクトによれば、TypeScriptをドキュメント化するニーズを満たしていない。

残念ながら、JSDocの文法は厳密に定義されていないため、特定の実装から振る舞いを推測せざるを得ないのが現状です。標準JSDocタグの大部分は、標準的なJavaScriptのタイプアノテーションの提供を目的としています。TypeScriptのように強く型付けされた言語にはまったく無関係なものです。

TSDocの構文は計画段階であり、公式にはリリースされていない。現段階でのプロジェクトは、TypeScriptチームとAPI Extractor、TypeDoc、DocFX、ts-docs-gen、Ember.jsの開発者たちからなる混成チームである。TypeScriptのプログラムマネージャであるDaniel Rosenwasser氏がInfoQに、TSDocを開発した動機について説明してくれた。

TSDocの開発活動は、TypeScript用のドキュメント生成ツールに関わる状況を改善したいという要求から組織的に始められました。その活動が大きな関心を集めて、いくつかのチームがこの問題に取り組み始めたのですが、やり方はそれぞれ少しずつ違っていました。今回の変更は、振る舞いを整理することに加えて、ドキュメントツールの作者が共通で抱える問題を特定する上で、共同作業を行なうまたとないチャンスだと私は捉えています。

プロジェクトではnpmパッケージ@microsoft/tsdocの公開と合わせて、TSDocパーザのリファレンス実装をオープンソースとして提供する予定である。

TSDocフォーマットは以下を目標としている。

• TypeScript用の文法設計とJSDocの拡張
• コメント内のマークダウンを可能にする
• ドキュメンテーションタグの共通セット
• タグを追加するための拡張機構
• カスタムタグが非カスタムタグの解釈やマークダウンのあいまいさの処理に影響しないような相互運用性
• パッケージと依存関係との相互参照
• オープン標準

さらにTSDocリファレンスパーザが、以下の目的で提供されている。

• Strictモードと、既存のJSDocベースの文法を解析するためのLaxモード
• ドキュメントコメントと抽象構文木の間の双方向ラウンドトリップ
• 自己完結型でTypeScriptコンパイラAPIに依存しないことで、コメントの抽象構文ツリーを単純なJavaScriptオブジェクトツリーにする

TypeScriptが提供する既存の型情報に対する冗長性を持つJSDocのタイプアノテーションは、TSDocではオプションになると予想されるものと予想される。

TSDocは初期段階であるため、プロジェクトでは、TSDocがすべてのTypeScriptソースコードを文書化するための有用なアプローチになるように支援してくれる開発関係者を広く求めている。TSDoc GitHubプロジェクトを通じてのコントリビューションも大歓迎だ。