TSDoc を書きたい & TSDoc で使えるタグ一覧

いつも TypeScript 書いてるんですよ、そしたら function の前にコメント書くじゃないですか、/** ... */ で書いてるけど正直のところ中身は勘で書いている。@returns や @deprecated とかよく見るし、雰囲気で使っているけど、本来なんのタグが使えるかあんまり誰も分かってない。補完のときに表示されてラッキーぐらいの感覚。でも謎のタグを使ってるの見たら気になるし、今 TypeDoc でドキュメント生成していなくても、標準的なフォーマットがあるなら従っておきたいじゃん。そして TSDoc でインターネットを検索しても、こう書けばいいみたいな記事がすぐ見つからねぇ〜〜

まだ標準は無い

リポジトリ見に行く

microsoft/tsdoc: A doc comment standard for the TypeScript language

ふむふむ、現行の多くのツールは大まかに JSDoc ベースのコメントをサポートしてるけど、JSDoc に厳密な文法が定義されてないので実装から挙動を推測しておりツールのパーサ間に非互換性がある、TypeScript では JSDoc に型を書くことに興味ない、TSDoc の仕様を作ろう、という感じ。

What's next:
Write up an initial draft of the TSDoc spec document, which outlines the proposed standard

はい...
2020-07-09 現在、標準の仕様は無くて最初のドラフトを作ってる段階。なのでこう書けみたいなドキュメントがないんだな。

とはいえ TSDoc が TypeScirpt のドキュメンテーションの標準になる確度は高いでしょう、何年も前からそういう雰囲気ではあるが。draft 前の実装はあるし、コア部分は大きく変わらなそう。TSDoc は JSDoc 表記に可能な限り近づけると言ってるし、JSDoc にないタグもあるけど JSDoc としてもパースできそう。なので現行の TSDoc のつもりでコメントを書いていっても悪くなることはないんじゃないか。

タグの種類と例

@ から始まるこういうのがタグ → @deprecated
タグには Inline, Block, Modifier の3種類ある。

Inline

{ } に囲まれて使われるインラインのタグ
{@link https://pokutuna.com} のように使う
@link, @inheritDoc, @label の3つ

Block

セクションの開始を表すタグ、後ろにドキュメントが続く
@deprecated, @example, @remarks, @param, @throws, @returns など

Modifier

ドキュメント対象を修飾するタグ、セクションを開始しない
Modifier に続くテキストは直前の Block の内容と見なされる
@override, @internal, @experimental など
TypeScirpt では型で定義される @readonly や @public なども一応? Modifier にある

エスケープ

タグのエスケープは @{} それぞれの前でバックスラッシュ
リンクテキストの例: \{\@link https://pokutuna.com | ぽくつなドットコム \} みたいな
エスケープではないけど Markdown が使えるので `` によって code span にしてもよい。

basicSample.ts を引用して注釈をつけるとこういう感じ

/**
 * Returns the average of two numbers.
 * ↑ Summary Section、見出しや要約のつもりで簡潔に書く
 *
 * @remarks
 * This method is part of the {@link core-library#Statistics | Statistics subsystem}.
 * ↑ 必要なら詳細を `@remarks` ブロックに書く
 *
 * @param x - The first input number
 * @param y - The second input number
 * @returns The arithmetic mean of `x` and `y`
 * ↑ これらも Block タグ
 *
 * @beta
 * ↑ ドキュメント対象を修飾する Modifier タグ
 */
function getAverage(x: number, y: number): number {
  return (x + y) / 2.0;
}

その他のサンプルは TSDoc Playground で見られる

タグ一覧

2020-07-09 現在 TSDoc で実装されているタグはこちら

ぞれぞれのタグの用途は実装 StandardTags.ts のコメントを見るとよい。

または TSDoc をサポートするツールの API Extractor のドキュメントが現状一番整っているように思うので参照するとよさそう API Extractor: Doc comment syntax。API Extractor は Microsoft のメンテする rushstack の一部で、TSDoc 開発者が作っている。

Tag	Kind	Standardization	AllowMultiple
@alpha	Modifier	Discretionary	false
@beta	Modifier	Discretionary	false
@deprecated	Block	Core	false
@defaultValue	Block	Extended	false
@eventProperty	Modifier	Extended	false
@example	Block	Extended	true
@experimental	Modifier	Discretionary	false
@inheritDoc	Inline	Extended	false
@internal	Modifier	Discretionary	false
@label	Inline	Core	false
@link	Inline	Core	true
@override	Modifier	Extended	false
@packageDocumentation	Modifier	Core	false
@param	Block	Core	true
@privateRemarks	Block	Core	false
@public	Modifier	Discretionary	false
@readonly	Modifier	Extended	false
@remarks	Block	Core	false
@returns	Block	Core	false
@sealed	Modifier	Extended	false
@see	Block	Extended	false
@throws	Block	Extended	true
@typeParam	Block	Core	true
@virtual	Modifier	Extended	false

Standardization は標準化のカテゴリで、Core は TSDoc に対応するツールが必須でサポートすべきもの、Extended はオプションだけど対応するなら構文とセマンティクスは TSDoc 仕様に従うべきもの、Discretionary もオプションだがセマンティクスは実装固有のもの、None は標準外のもの(カスタムタグなどで定義したらこれになる？)

AllowMultiple は1つのコメントブロック(/** ... */)で複数使えるなら true。Modifier はその性質上 false ですね。

感想

@deprecated が Block タグなのは、今はこれ使えとか、どのバージョンから非推奨かなどを書く想定ってことやね。

JSDoc ではおもむろ長文書きがちだが、@remarks でセクション分けてほしそう、ユーザに配布するドキュメントなどに出力したくないものは @privateRemarks を使う。

@packageDocumentation は直後の実装を修飾するわけでなくて、package に対する説明であることを表明するやつ。API Extractor: @packageDocumentation

@see は1つしか書けないのはやや意外、一方 @example は複数書けるので、例ごとにセクションを分けよう。

@label は {@label hoge} で付けたラベルを {@link hogeNamespace.(:hoge)} のように参照するものらしい、やや難しい印象だけど Core である。@link は URL だけでなくコード上の識別子でも参照できるため、記法を決めるのにいろいろ議論がある。 RFC: Syntax for "declaration references" (hyperlinks) · Issue #9 · microsoft/tsdoc

TSDoc のコードに手を入れず拡張する仕組みとして @microsoft/tsdoc-config がある。JSON を書いたらカスタムタグとして追加できる。また eslint-plugin-tsdoc で TSDoc コメントの lint ができる、どちらも TSDoc リポジトリ内にある。

VS Code によるサポート

実際のところ VSCode で TypeScirpt を書く時は、まだ TSDoc は標準ではないし、JSDoc Support の機能によってもろもろ表示されていそう。

JSDoc support / TypeScript Programming with Visual Studio Code

なので Block や Modifier の仕様は関係なくて @ で区切られた文字列をタグとみなして表示が整えられている。TSDoc のように Markdown も使えるし、Code Block は Syntax Highlight もされる。

VSCode 上での表示

実際のところ多くのユーザは JSDoc であまり困っていなくて、JSDoc をパースしてなんかやりたい人やツールが困ってるって感じなんだろうな。なら今書こうとしてるのは何なのかという気持ちになるけど、将来俺は昔から TSDoc でやってきたという顔をするために TSDoc で書きます。