宣言参照

{@inheritdoc} や {@link} などの特定のタグは、クラス、メンバ関数、列挙値など、他の API アイテムを参照できます。参照されるアイテムはローカルの場合もあれば、外部の NPM パッケージからインポートされた場合もあります。マージされた宣言やオーバーロードされた関数の一部である可能性もあります。

TSDoc 構文は、これらの状況ですべての宣言を明確に識別するための特別な「**宣言参照**」表記を提供します。(TSDoc のこの側面はまだ進化しています。 RFC #9 で追跡されています。現在の仕様は code-snippets/DeclarationReferences.ts に概説されています。)

構文例

以下は、宣言参照の記述を開始するのに役立つ構文例です。

単純なローカル宣言

/** @public */
export class Widget {
  /**
   * Call this before calling the {@link Widget.render | the render() method}.
   */
  public initialize(): void {}

  public render(): void {}
}

同じプロジェクト内の宣言を参照するには、その名前を単に使用し、入れ子になったメンバーを範囲指定するには「.」を使用します。上記の例では、Widget.render は Widget クラスの render メソッドを参照します。一致が一意であれば、メンバーがstaticであるかどうかに関係ありません。

TSDoc 宣言参照は、常に特定のエントリポイントを基準に解決されます（現在のソースファイルまたは宣言スコープを基準にはしません）。したがって、その構文は、特定のパッケージ内のどこで参照が発生するかに依存しません。Widget.initializeがWidget内にあるため、参照を{@link render | the render() method}に短縮したい場合がありますが、TSDoc標準ではこれがサポートされていません。

インポートされた宣言

import { Widget } from '@my-org/widget-lib';

/**
 * Returns a new instance of the {@link @my-org/widget-lib#Widget} class.
 * @public
 */
export function createWidget(): Widget {
  . . .
}

NPM パッケージからインポートされた宣言を参照するには、パッケージ名に続けて「#」文字を指定します（例: widget-lib#Widget）。パッケージ名にNPMスコープがある場合は、それも含めることができます（例: @my-org/widget-lib#Widget）。

パッケージ全体

import { Button } from 'controls';

/**
 * Constructs a `Button` as defined by the {@link controls#} library.
 * @public
 */
export function createButton(): Button {
  . . .
}

特定のエクスポートではなくパッケージ全体を参照するには、上記のようにメンバー名を省略します。ただし、「#」文字を含める必要があります。そうでないと、controlsは、その名前の宣言への参照のように見えます。

マージされた宣言

/** @public */
export enum ShirtSize {
  Small,
  Medium,
  Large
}

/** @public */
export namespace ShirtSize {
  /**
   * Parses a string and returns an instance of the
   * {@link (ShirtSize:enum)} enum.
   */
  export function parseName(name: string): ShirtSize {
    switch (name) {
      case 'S':
        return ShirtSize.Small;
      case 'M':
        return ShirtSize.Small;
      case 'L':
        return ShirtSize.Large;
    }
    throw new Error('Invalid size');
  }
}

上記の例では、シンボルShirtSizeは列挙型と名前空間の両方です。単に{@link ShirtSize}と記述した場合、API Extractorは次のような警告を報告します。

Warning: (ae-unresolved-link) The @link reference could not be resolved:
The reference is ambiguous because "ShirtSize" has more than one declaration;
you need to add a TSDoc member reference selector

(ShirtSize:enum)表記は、TSDocシステムセレクタを使用して、名前空間ではなく列挙型について話していることを明確にしています。

サポートされていない機能

API Extractor は TSDoc 宣言参照のすべての主要な機能をサポートしていますが、仕様で説明されているいくつかの高度な機能はまだサポートされていません。

• インデックスセレクタ
• ラベルセレクタ
• 識別子の代わりに ECMAScript シンボルを使用した参照
• インポートパス

これらの機能は将来実装される可能性があります。貢献したい場合は、AstReferenceResolver.ts と ModelReferenceResolver.ts のコードを確認してください。