文件註釋語法

API Extractor 會剖析您的 TypeScript 程式碼註釋，以取得文件和額外的類型資訊。它預期您的程式碼註釋使用 TSDoc 格式。我們在此不提供語法的完整說明；請參考 TSDoc 專案。）如果您曾將 JSDoc 用於 JavaScript 原始碼，TSDoc 將非常相似，但請注意，有一些語法差異。

可以透過定義自訂標籤來擴充 TSDoc 語言。API Extractor 特定的 TSDoc 語言稱為「AEDoc」。(API Extractor 6.x 開始支援 TSDoc。在較早的版本中，API Extractor 使用也稱為「AEDoc」的專有語法，但現在已淘汰。)

TSDoc Playground
順帶一提，TSDoc Playground 網站提供了一種互動式的方式來試驗程式碼註釋，以查看它們將如何被剖析。試試看！

API Extractor 會剖析哪些註釋？

API Extractor 要剖析程式碼註釋，必須滿足以下所有條件

註釋必須出現在類別的 .d.ts 檔案中
註釋必須以特殊的 /** 分隔符號（兩個星號）開頭
註釋必須緊接在匯出的宣告之前；或者註釋出現在進入點檔案的頂端，並且包含 @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) {
    . . .
  }
}

發行標籤

四個發行標籤為：@internal、@alpha、@beta、@public。它們套用於 API 項目，例如類別、成員函式、列舉等。API Extractor 會根據其預期的支援級別，單獨分類每個匯出的 API 項目

internal：表示 API 項目僅供來自相同維護者的其他 NPM 套件使用。第三方 niemals "internal" APIs verwenden sollen. Um dies zu betonen, sollten Unterstrichpräfixe für Elemente mit einem (expliziten) `@internal`-Tag verwendet werden.
alpha：表示 API 項目最終將公開發布，但目前處於開發初期階段。第三方不應使用「alpha」API。
beta：表示 API 項目已作為預覽或實驗用途發布。鼓勵第三方試用並提供意見反應。但是，不應在生產環境中使用「beta」API，因為它可能會在 zukünftigen Versionen geändert oder entfernt werden.
public：表示 API 項目已正式發布，現在是套件支援合約的一部分。如果使用 SemVer 版本控制機制，則 API 簽章在沒有主要版本遞增的情況下無法更改。

注意：TypeScript 的 public/protected/private 關鍵字與 AEDoc 發行標籤無關。例如，成員函式通常會有 public TypeScript 關鍵字，無論它在文件註釋中被分類為 @public 還是 @internal。

API 首次引入時，通常從 **alpha** 開始。隨著設計的成熟，它會從 **alpha** -> **beta** -> **public** 逐步發展。「內部」名稱主要用於解決管線問題，通常不在公開發布的路線圖上。（還有一個 @deprecated 標籤，但它是可以與上述任何標籤組合的選項。）

發行標籤遞迴地套用於容器（例如類別或介面）的成員。例如，如果類別標記為 @beta，則其所有成員自動具有此狀態；您不需要將 @beta 標籤新增至每個成員函式。但是，您可以將 @internal 新增至成員函式，以賦予其不同的發行狀態。

注意：如果容器（例如類別或介面）具有 @internal 標籤，則應在其名稱前新增底線前綴，但其成員不需要底線。而例如，如果將 @internal 套用於 @beta 類別的成員函式，則內部函式應具有底線前綴。

最後，請注意某些邏輯規則適用。例如，@public 函式不應傳回 @beta 類型。@beta 類別不應繼承自 @internal 基底類別。等等。API Extractor 目前不驗證這些規則，但很快就會驗證。

API Extractor 會剖析哪些註釋？​

註釋結構​

發行標籤​

另請參閱​

API Extractor 會剖析哪些註釋？

註釋結構

發行標籤

另請參閱