TSDoc
なんかちょっと書こうと思っても全然書き方わからんやんけ
標準仕様はまだない
What's next:
Write up an initial draft of the TSDoc spec document, which outlines the proposed standard
Collect community feedback and integrate it into the draft, then publish the first "official" 1.0 spec
サンプル
公式の Playground 以上のやつはなさそう
セクション分けのイメージや Markdown 書けることなど、長めのサンプル
なんかここが一番書き方まとまってる気がする
こういうのが TSDoc リポジトリトップあると嬉しいが、仕様策定中感を損ないたくないんだろうな
d.ts を rollup したり同 stack の api-documenter が使う API ドキュメントモデルを生成したり
元は AEDoc という独自の構文だったけど TSDoc を使うようになった
Microsoft がメンテしてる & TSDoc の開発者がやっている
タグ一覧
@なんとか のやつ
@alpha, @beta, @deprecated, @defaultValue, @eventProperty, @example, @experimental, @inheritDoc, @internal, @label, @link, @override, @packageDocumentation, @param, @privateRemarks, @public, @readonly, @remarks, @returns, @sealed, @see, @throws, @typeParam, @virtual
使い方は StandardTags.ts の tsdoc に書いてある
SyntaxKind
タグの種類
InlineTag
インラインで {} に囲まれて使われるもの
@inheritDoc、@label、@link
@link ぐらいかな普段使いそうなのは
{@link MyClass} や {@link https://pokutuna.com} みたいに
BlockTag
新しいセクションの開始
@deprecated, @defaultValue, @example, @param, @privateRemarks, @remarks, @returns, @see, @throws, @typeParam
よく目にするやついろいろある
行内で完結することがほとんどに見えるけど、@example, や @remarks は改行のあとに文章が来るのが多い
code:remarks.ts
export class Employee {
/**
* The employee's first name.
*
* @remarks
* The first name may contain Unicode characters.
*/
public firstName: string;
...
ModifierTag
そのコメントブロックの対象を修飾するタグ
@alpha, @beta, @eventProperty, @experimental, @internal, @override, @packageDocumentation, @public, @readonly, @sealed, @virtual
使いそうなのは @internal, @override ぐらいかな?
@public やら @readonly やらはコードで表現するだろう
@deprecated がこっちじゃないのは、後ろにテキストがくるからかな?
@deprecated use HogeClass みたいな
逆に ModifierTag はタグ単体で意味ある感じやね
@eventProperty はなんか普段見ない感じがする
this indicates that the property returns an event object that event handlers can be attached to. The event-handling API is implementation-defined, but typically the property return type would be a class with members such as addHandler() and removeHandler().
@beta と @experimental はシノニム同士
コメントブロックの最初には置かない
この記述 TSDoc で StandardTags.ts パースすれば自動で作れそう
code:gen.ts
import * as tsdoc from '@microsoft/tsdoc';
function toKindName(kind: tsdoc.TSDocTagSyntaxKind): string {
switch (kind) {
case tsdoc.TSDocTagSyntaxKind.InlineTag:
return 'Inline';
case tsdoc.TSDocTagSyntaxKind.BlockTag:
return 'Block';
case tsdoc.TSDocTagSyntaxKind.ModifierTag:
return 'Modifier';
}
}
tsdoc.StandardTags.allDefinitions.forEach(tag => {
console.log([
tag.tagName,
toKindName(tag.syntaxKind),
tag.standardization,
tag.allowMultiple,
]);
});
Standardization
タグの標準化のグループ
Core / Extended / Discretionary / None
Core は標準化されてドキュメントツールがサポートすると想定されてるもの
Extended はサポートしたりしなかったり、サポートするなら構文とセマンティクスはならう必要がある
Discretionary セマンティクスはドキュメントツールの実装固有
標準に書いてあったら従うのを期待するのでは??
@alpha や @internal の意味するところは状況によりけりって感じかねえ
None 標準ではない
TSDoc に無い
JSDoc 由来のものを書いてんるだろうけど、どうなのかと思う、Custom Tag で増やしたりはできるが...
The TSDoc standard guarantees that unsupported custom tags won't interfere with parsing of other content.
なので、カスタムタグがあっても問題ないのは問題ない
@since
@requires
タグの拡張
パーサコードに手を入れず拡張する仕組み
code:tsdoc.json
{
"tagDefinitions": [
{
"tagName": "@myTag",
"syntaxKind": "modifier"
}
]
}
やってないけどこれで生成したら standardization.None になるんかな?
気になる
実際のところ VSCode など主要なエディタでどう扱われているのか、TSDoc のサポートしてない範囲でもなんか JSDoc として読んだり強調したり連携する機能あるのか ある
https://gyazo.com/5b2913d7e7cada692ddaf8bd31d6b1e6
content のない BlockTag、単に @deprecated って書くとどうなる?
TypeDoc & VSCode で
まあ普通に表示される
https://gyazo.com/5ac955ac4a350112484df2dc45f25306https://gyazo.com/0824732160af4cf43c87d657b7a4f15a
Modifier でも後ろのテキストは紐づく
@public とかは TypeDoc はメソッドが Public なら無視しそう、つまり Modifier ごとに対応があるかも
@public の後ろのメッセージはドキュメントに出力されない
@beta 等は @internalと同じように解釈される
code:blockAndModifier.ts
/**
* @deprecated
* @internal
* This message is content of @internal
*/
export function fnContentAndModifier1() {}
/**
* @deprecated
* @public
* This message is content of @public?
*/
export function fnContentAndModifier2() {}
https://gyazo.com/ddbf089b42871482066af56b3c6818b9https://gyazo.com/114cccd6a2251ed2caf8333839334ac3
@ のエスケープどうする
\{\@inheritDoc Button.render\} にする example https://gyazo.com/725e44959a239174fbe25e38a65b773chttps://gyazo.com/6507c58df839e11fdb5bc151c02a32fe
Link
良いスライド