Rush Stackショップブログイベント
本文へスキップ

ドキュメントコメント構文

API Extractor は、TypeScript コードのコメントを解析して、ドキュメントと追加の型情報を取得します。コードコメントには TSDoc 形式を使用する必要があります。ここでは、文法の完全な説明は提供しません。代わりに、TSDoc プロジェクト を参照してください。JavaScript ソースコードに JSDoc を使用したことがある場合、TSDoc は非常に似ていますが、構文の違いに注意してください。

TSDoc 言語は、カスタムタグを定義することで拡張できます。API Extractor の TSDoc の特定の方言は「AEDoc」と呼ばれています。（TSDoc のサポートは API Extractor 6.x で導入されました。以前のリリースでは、API Extractor は「AEDoc」とも呼ばれる独自の構文を使用していましたが、これは現在廃止されています。）

TSDoc Playground

ちなみに、TSDoc Playground ウェブサイトでは、コードコメントをインタラクティブに試して、どのように解析されるかを確認できます。ぜひお試しください！

API Extractor によって解析されるコメントは？​

API Extractor がコードコメントを解析するためには、次のすべてが真である必要があります。

  • コメントは、クラスの出力された .d.ts ファイルに表示されている必要があります。
  • コメントは、特別な `/**` デリミタ（アスタリスク 2 つ）で始まる必要があります。
  • コメントはエクスポートされた宣言の直前に表示されている必要があります。または、コメントはエントリポイントファイルの先頭に表示され、`@packageDocumentation` タグが含まれている必要があります。

宣言に複数のコメントブロックがある場合、最も近いものだけが考慮されることに注意してください。例：

/**
 * Comment for f1.
 */
export function f1(): void {}

/**
 * THIS COMMENT WILL BE IGNORED ENTIRELY.
 */

/**
 * Comment for f2.
 */
export function f2(): void {}

コメント構造​

TSDoc コメントの全体的な構造には、次のコンポーネントがあります。

  • サマリーセクション：最初のブロックタグまでのドキュメント内容は「サマリー」と呼ばれます。サマリーセクションは簡潔にする必要があります。ドキュメントウェブサイトでは、多くの異なる API 項目のサマリーを一覧表示するページに表示されます。単一の項目の詳細ページでは、サマリーが続き、その後に解説セクション（存在する場合）が表示されます。
  • 解説ブロック：「解説」ブロックは `@remarks` ブロックタグで始まります。サマリーとは異なり、解説には長いドキュメントコンテンツを含めることができます。解説セクションでは、サマリーの情報は繰り返さないようにしてください。サマリーセクションは、解説セクションが表示される場所であれば常に表示されます。
  • 追加のブロック：他の TSDoc ブロックは通常、`@remarks` ブロックに続きます。各ブロックは、`@param`、`@returns`、`@example` などのブロックタグで導入されます。
  • 修飾子タグ：修飾子タグは通常、最後にきます。修飾子タグには、関連付けられたコンテンツブロックがありません。代わりに、その存在は宣言の側面を示しています。修飾子タグの例としては、`@public`、`@beta`、`@virtual` などがあります。
  • インラインタグ：インラインタグはどのセクションにも表示でき、常に `{` と `}` 文字で区切られます。タグ名と `}` デリミタの間に追加のコンテンツが表示される場合があります。その形式はタグ固有です。インラインタグの例としては、`{@link}` と `{@inheritDoc}` があります。

ドキュメントコメント構文のさまざまなコンポーネントをすべて示すサンプルコードを次に示します。

/**
 * The base class for all widgets.
 *
 * @remarks
 * For details, see {@link https://example.com/my-protocol | the protocol spec}.
 *
 * @public
 */
export abstract class BaseWidget {
  /**
   * Draws the widget.
   * @remarks
   *
   * The `draw` member implements the main rendering for a widget.
   *
   * @param force - whether to force redrawing
   * @returns true, if rendering occurred; false, if the view was already up to date
   *
   * @beta @virtual
   */
  public draw(force: boolean): boolean {
    . . .
  }

  /**
   * Whether the widget is currently visible.
   *
   * @example
   * Here's some example code to hide a widget:
   *
   * ```ts
   * let myWidget = new MyWidget();
   * myWidget.visible = false;
   * ```
   *
   * @defaultValue `true`
   */
  public visible: boolean = true;

  /**
   * Gets or set the title of this widget
   */
  public get title(): string {
    . . .
  }

  // NOTE: API Extractor considers your property getter and setter functions to be
  // a single API item.  Don't write any documentation for the setter.
  public set title(value: string) {
    . . .
  }
}

リリースタグ​

4 つのリリースタグは、`@internal`、`@alpha`、`@beta`、`@public` です。これらは、クラス、メンバ関数、列挙型などの API 項目に適用されます。API Extractor は、意図されたサポートレベルに従って、各エクスポートされた API 項目を個別に分類します。

  • internal：API 項目が、同じメンテナンス担当者からの他の NPM パッケージでのみ使用することを意図していることを示します。サードパーティは、「internal」API を決して使用しないでください。これを強調するために、（明示的な）`@internal` タグが付いた項目には、アンダースコアプレフィックスを使用する必要があります。

  • alpha：API 項目が最終的には公開されることを意図していますが、現在開発の初期段階にあることを示します。サードパーティは「alpha」API を使用しないでください。

  • beta：API 項目がプレビューとして、または実験目的でリリースされたことを示します。サードパーティは試してみてフィードバックを提供することをお勧めします。「beta」API は、将来のバージョンで変更または削除される可能性があるため、本番環境で使用しないでください。

  • public：API 項目が正式にリリースされ、パッケージのサポート対象契約の一部になったことを示します。SemVer バージョン管理スキームが使用されている場合、API シグネチャはメジャーバージョンをインクリメントせずに変更できません。

注：TypeScript の `public` / `protected` / `private` キーワードは、AEDoc リリースタグとは関係ありません。たとえば、メンバ関数は、ドキュメントコメントで `@public` または `@internal` として分類されているかどうかに関係なく、通常は `public` TypeScript キーワードを持ちます。

API が最初に導入されると、通常は **alpha** から始まります。設計が成熟するにつれて、**alpha** -> **beta** -> **public** に移行します。**internal** 指定は主に配管の問題を解決するために使用され、通常は公開されるロードマップにはありません。（`@deprecated` タグもありますが、上記のタグのいずれかと組み合わせることができるオプションです。）

リリースタグは、コンテナ（例：クラスまたはインターフェース）のメンバーに再帰的に適用されます。たとえば、クラスが `@beta` とマークされている場合、そのすべてのメンバーは自動的にこの状態になります。各メンバ関数に `@beta` タグを追加する必要はありません。ただし、メンバ関数に `@internal` を追加して、異なるリリース状態にすることができます。

注：コンテナ（例：クラスまたはインターフェース）に `@internal` タグがある場合、その名前にはアンダースコアプレフィックスを追加する必要がありますが、そのメンバーにはアンダースコアは必要ありません。一方、たとえば `@beta` クラスのメンバ関数に `@internal` が適用されている場合、内部関数にはアンダースコアプレフィックスを追加する必要があります。

最後に、特定の論理規則が適用されることに注意してください。たとえば、`@public` 関数は `@beta` 型を返すことはできません。`@beta` クラスは `@internal` 基本クラスを継承することはできません。など。API Extractor は現在これらの規則を検証していませんが、すぐに検証される予定です。

参照​