@use JSDoc

教學

JSDoc 讓您可以在 API 文件中加入教學。您可以使用此功能提供使用 API 的詳細說明，例如「入門」指南或實作功能的逐步程序。

加入教學

若要將教學加入 API 文件，請使用 --tutorials 或 -u 選項執行 JSDoc，並提供 JSDoc 應搜尋教學的目錄。例如

jsdoc -u 路徑/至/教學 路徑/至/js/檔案

JSDoc 會在教學目錄中搜尋具有下列副檔名的檔案

JSDoc 也會搜尋包含教學標題、順序和層級資訊的 JSON 檔案，如下一節所述。

JSDoc 會為每個教學指定一個識別碼。識別碼是檔案名稱，不含副檔名。例如，/路徑/至/教學/概觀.md 的識別碼是 概觀。

在教學檔案中，您可以使用 {@link} 和 {@tutorial} 內嵌標籤連結到文件中的其他部分。JSDoc 會自動解析連結。

設定標題、順序和層級

預設情況下，JSDoc 會使用檔案名稱作為教學標題，且所有教學都處於同一層級。您可以使用 JSON 檔案為每個教學提供標題，並指出教學應如何排序和分組在文件中。

JSON 檔案必須使用副檔名 .json。在 JSON 檔案中，您可以使用教學識別碼為每個教學提供兩個屬性

在 JSDoc 3.2.0 及更新版本中，您可以使用下列格式的 JSON 檔案

  1. 物件樹，其中子教學定義在父教學的 子項 屬性中。例如，如果 教學1 有兩個子項，子項 A 和 子項 B，而 教學2 與 教學1 處於同一層級，且沒有子項

    {
    "tutorial1": {
        "title": "Tutorial One",
        "children": {
            "childA": {
                "title": "Child A"
            },
            "childB": {
                "title": "Child B"
            }
        }
    },
    "tutorial2": {
        "title": "Tutorial Two"
    }
}

  2. 其屬性皆為教學物件的頂層物件，其中子教學課程以陣列中的名稱列出。例如，如果 tutorial1 有兩個子項，childA 和 childB，且 tutorial2 與 tutorial1 處於同一層級且沒有子項

    {
    "tutorial1": {
        "title": "Tutorial One",
        "children": ["childA", "childB"]
    },
    "tutorial2": {
        "title": "Tutorial Two"
    },
    "childA": {
        "title": "Child A"
    },
    "childB": {
        "title": "Child B"
    }
}

您也可以為每個教學課程提供個別的 .json 檔案，並使用教學課程識別碼作為檔案名稱。此方法已過時，不應使用於新專案。

從 API 文件連結到教學課程

有多種方式可以從您的 API 文件連結到教學課程

@tutorial 區塊標籤

如果您在 JSDoc 註解中包含 @tutorial 區塊標籤，產生的文件將包含連結到您指定的教學課程。

使用 `@tutorial` 區塊標籤
/**
 * Class representing a socket connection.
 *
 * @class
 * @tutorial socket-tutorial
 */
function Socket() {}

{@tutorial} 內嵌標籤

您也可以使用 {@tutorial} 內嵌標籤 在另一個標籤的文字中連結到教學課程。預設情況下，JSDoc 會使用教學課程的標題作為連結文字。

使用 `{@tutorial}` 內嵌標籤
/**
 * Class representing a socket connection. See {@tutorial socket-tutorial}
 * for an overview.
 *
 * @class
 */
function Socket() {}