@use JSDoc

使用設定檔設定 JSDoc

設定檔格式

若要自訂 JSDoc 的行為，您可以使用下列其中一種格式提供設定檔給 JSDoc

若要使用設定檔執行 JSDoc，請使用 -c 命令列選項（例如，jsdoc -c /path/to/conf.json 或 jsdoc -c /path/to/conf.js）。

下列範例顯示一個啟用 JSDoc Markdown 外掛程式 的簡單設定檔。JSDoc 的設定選項會在下列各節中詳細說明。

JSON 設定檔
{
    "plugins": ["plugins/markdown"]
}
JavaScript 設定檔
'use strict';

module.exports = {
    plugins: ['plugins/markdown']
};

若要取得 JSON 設定檔的更全面範例，請參閱檔案 conf.json.EXAMPLE。

預設設定選項

如果您未指定設定檔，JSDoc 會使用下列設定選項

{
    "plugins": [],
    "recurseDepth": 10,
    "source": {
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "sourceType": "module",
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    },
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}

這表示

這些選項和其他選項會在下列各節中說明。

設定外掛程式

若要啟用外掛程式，請將其路徑（相對於 JSDoc 資料夾）新增至 plugins 陣列中。

例如，下列 JSON 組態檔將會啟用 Markdown 外掛程式，它會將 Markdown 格式的文字轉換為 HTML，以及「summarize」外掛程式，它會自動為每個 doclet 產生摘要

包含外掛程式的 JSON 組態檔
{
    "plugins": [
        "plugins/markdown",
        "plugins/summarize"
    ]
}

請參閱 外掛程式參考 以取得更多資訊，並查看 JSDoc 的 plugins 目錄 以取得 JSDoc 內建的外掛程式。

您可以透過將 markdown 物件新增至組態檔來組態 Markdown 外掛程式。請參閱 組態 Markdown 外掛程式 以取得詳細資料。

指定遞迴深度

recurseDepth 選項控制 JSDoc 遞迴搜尋原始檔和教學課程的深度。此選項在 JSDoc 3.5.0 及更新版本中提供。此選項僅在您也指定 -r 命令列旗標 時使用，此旗標會指示 JSDoc 遞迴搜尋輸入檔。

{
    "recurseDepth": 10
}

指定輸入檔

source 選項組，搭配命令列中傳遞給 JSDoc 的路徑，決定 JSDoc 用於產生文件的一組輸入檔。

{
    "source": {
        "include": [ /* array of paths to files to generate documentation for */ ],
        "exclude": [ /* array of paths to exclude */ ],
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    }
}

這些選項會以下列順序詮釋

  1. 從命令列和 source.include 中提供的所有路徑開始。
  2. 對於在步驟 1 中找到的每個檔，如果存在正規表示式 source.includePattern，則檔名必須符合它，否則會被忽略。
  3. 對於從步驟 2 中遺留的每個檔案，如果存在正規表示式 source.excludePattern，則會忽略與此正規表示式相符的任何檔案名稱。
  4. 對於從步驟 3 中遺留的每個檔案，如果檔案路徑位於 source.exclude 中，則會忽略該檔案。

在執行完這四個步驟後，JSDoc 會處理所有剩餘的檔案。

例如，假設您有以下檔案結構

myProject/
|- a.js
|- b.js
|- c.js
|- _private
|  |- a.js
|- lib/
   |- a.js
   |- ignore.js
   |- d.txt

此外，假設您的 conf.json 檔案看起來像這個範例

{
    "source": {
        "include": ["myProject/a.js", "myProject/lib", "myProject/_private"],
        "exclude": ["myProject/lib/ignore.js"],
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    }
}

如果您從包含 myProject 資料夾的檔案執行 jsdoc myProject/c.js -c /path/to/my/conf.json -r，則 JSDoc 將為以下檔案產生文件

原因如下

  1. 根據 source.include 和命令列中提供的路徑，JSDoc 會從這些檔案開始
    • myProject/c.js（來自命令列）
    • myProject/a.js（來自 source.include）
    • myProject/lib/a.js、myProject/lib/ignore.js、myProject/lib/d.txt（來自 source.include 並使用 -r 選項）
    • myProject/_private/a.js（來自 source.include）
  2. JSDoc 套用 source.includePattern，留下上述所有檔案，除了 myProject/lib/d.txt，它不是以 .js、.jsdoc 或 .jsx 結尾。
  3. JSDoc 套用 source.excludePattern，移除 myProject/_private/a.js。
  4. JSDoc 套用 source.exclude，移除 myProject/lib/ignore.js。

指定來源類型

sourceType 選項會影響 JSDoc 解析 JavaScript 檔案的方式。此選項在 JSDoc 3.5.0 及後續版本中提供。此選項接受下列值

{
    "sourceType": "module"
}

將命令列選項納入組態檔

您可以將許多 JSDoc 的 命令列選項 放入組態檔中，而不是在命令列中指定它們。為此，請將相關選項的長名稱新增到組態檔的 opts 區段中，並將值設定為選項的值。

包含命令列選項的 JSON 組態檔
{
    "opts": {
        "template": "templates/default",  // same as -t templates/default
        "encoding": "utf8",               // same as -e utf8
        "destination": "./out/",          // same as -d ./out/
        "recurse": true,                  // same as -r
        "tutorials": "path/to/tutorials", // same as -u path/to/tutorials
    }
}

透過使用 source.include 和 opts 選項，您可以將幾乎所有 JSDoc 的引數放入組態檔中，以便將命令列簡化為

jsdoc -c /path/to/conf.json

當選項在命令列和組態檔中指定時，命令列優先。

組態標籤和標籤字典

tags 中的選項控制允許哪些 JSDoc 標籤以及如何詮釋每個標籤。

{
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    }
}

tags.allowUnknownTags 屬性會影響 JSDoc 處理未識別標籤的方式。如果您將此選項設定為 false，而 JSDoc 找到它不識別的標籤（例如 @foo），JSDoc 會記錄警告。預設情況下，此選項設定為 true。在 JSDoc 3.4.1 及後續版本中，您也可以將此屬性設定為 JSDoc 應允許的標籤名稱陣列（例如 ["foo","bar"]）。

tags.dictionaries 屬性控制 JSDoc 識別哪些標籤，以及 JSDoc 如何詮釋它識別的標籤。在 JSDoc 3.3.0 及後續版本中，有兩個內建標籤字典

預設情況下，兩個字典都已啟用。此外，預設情況下，jsdoc 字典會先列出；因此，如果 jsdoc 字典處理標籤的方式與 closure 字典不同，jsdoc 版本的標籤會優先。

如果將 JSDoc 與 Closure Compiler 專案搭配使用，而且您想要避免使用 Closure Compiler 無法辨識的標籤，請將 tags.dictionaries 設定變更為 ["closure"]。如果您想要允許核心 JSDoc 標籤，但想要確保 Closure Compiler 特定的標籤會以 Closure Compiler 的方式來詮釋，也可以將此設定變更為 ["closure","jsdoc"]。

設定範本

templates 中的選項會影響產生文件的樣式和內容。第三方範本可能無法實作所有這些選項。請參閱 設定 JSDoc 的預設範本，以取得預設範本支援的其他選項。

{
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}

如果 templates.monospaceLinks 為 true，所有來自 內嵌 {@link} 標籤 的連結文字都會以等寬字體呈現。

如果 templates.cleverLinks 為 true，如果 asdf 是網址，{@link asdf} 會以一般字體呈現，否則會以等寬字體呈現。例如，{@link http://github.com} 會以純文字呈現，但 {@link MyNamespace.myFunction} 會以等寬字體呈現。

如果 templates.cleverLinks 為 true，templates.monospaceLinks 會被忽略。