使用配置文件配置 JSDoc

配置文件格式

要自定义 JSDoc 的行为，你可以使用以下格式之一向 JSDoc 提供配置文件

• JSON 文件。在 JSDoc 3.3.0 及更高版本中，此文件可以包含注释。
• 导出单个配置对象的 CommonJS 模块。此格式在 JSDoc 3.5.0 及更高版本中受支持。

要使用配置文件运行 JSDoc，请使用 -c 命令行选项（例如，jsdoc -c /path/to/conf.json 或 jsdoc -c /path/to/conf.js）。

以下示例显示了一个简单的配置文件，它启用了 JSDoc 的 Markdown 插件。JSDoc 的配置选项在以下部分中进行了详细说明。

{
    "plugins": ["plugins/markdown"]
}

'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
    }
}

这意味着

• 未加载任何插件（plugins）。
• 如果使用 -r 命令行标志 启用了递归，JSDoc 将搜索 10 级深度的文件（recurseDepth）。
• 仅处理以 .js、.jsdoc 和 .jsx 结尾的文件（source.includePattern）。
• 将忽略以下划线开头或位于以下划线开头的目录中的任何文件（source.excludePattern）。
• JSDoc 支持使用 ES2015 模块（sourceType）的代码。
• JSDoc 允许你使用未识别的标签（tags.allowUnknownTags）。
• 标准 JSDoc 标签和 Closure 编译器标签 均已启用（tags.dictionaries）。
• 内联 {@link} 标签 以纯文本形式呈现（templates.cleverLinks、templates.monospaceLinks）。

这些选项和其他选项在以下部分中进行了说明。

配置插件

要启用插件，请将它们的路径（相对于 JSDoc 文件夹）添加到 plugins 数组中。

例如，以下 JSON 配置文件将启用 Markdown 插件（它将 Markdown 格式的文本转换为 HTML）和“summarize”插件（它为每个文档自动生成摘要）

{
    "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": "(^|\\/|\\\\)_"
    }
}

• source.include：一个可选路径数组，其中包含 JSDoc 应为其生成文档的文件。在命令行中提供给 JSDoc 的路径与这些路径结合使用。您可以使用 -r 命令行选项 递归到子目录中。
• source.exclude：一个可选路径数组，JSDoc 应忽略该数组。在 JSDoc 3.3.0 及更高版本中，此数组可能包括 source.include 中路径的子目录。
• source.includePattern：一个可选字符串，解释为正则表达式。如果存在，则所有文件名必须与此正则表达式匹配才能由 JSDoc 处理。默认情况下，此选项设置为 ".+\.js(doc|x)?$", 这意味着仅处理扩展名为 .js、.jsdoc 和 .jsx 的文件。
• source.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 将为以下文件生成文档

• myProject/a.js
• myProject/c.js
• myProject/lib/a.js

原因如下

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 及更高版本中可用。此选项接受以下值

• module（默认）：对大多数类型的 JavaScript 文件使用此值。
• script：如果 JSDoc 在解析代码时记录诸如 Delete of an unqualified identifier in strict mode 之类的错误，请使用此值。

{
    "sourceType": "module"
}

将命令行选项合并到配置文件中

您可以将许多 JSDoc 的 命令行选项 放入配置文件中，而不是在命令行中指定它们。为此，将相关选项的长名称添加到配置文件的 opts 部分，并将值设置为该选项的值。

{
    "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：Closure 编译器标签。

默认情况下，两个词典都已启用。此外，默认情况下，jsdoc 词典首先列出；因此，如果 jsdoc 词典处理标签与 closure 词典不同，则 jsdoc 版本的标签优先。

如果你将 JSDoc 与 Closure 编译器项目一起使用，并且你希望避免使用 Closure 编译器无法识别的标签，请将 tags.dictionaries 设置更改为 ["closure"]。如果你希望允许核心 JSDoc 标签，但你希望确保 Closure 编译器特定标签被解释为 Closure 编译器将解释它们的方式，你还可以将此设置更改为 ["closure","jsdoc"]。

配置模板

templates 中的选项会影响生成文档的外观和内容。第三方模板可能无法实现所有这些选项。有关默认模板支持的其他选项，请参见 配置 JSDoc 的默认模板。

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

如果 templates.monospaceLinks 为真，则来自 内联 {@link} 标签 的所有链接文本都将以等宽字体呈现。

如果 templates.cleverLinks 为真，则当 asdf 是 URL 时，{@link asdf} 将以正常字体呈现，否则以等宽字体呈现。例如，{@link http://github.com} 将以纯文本呈现，但 {@link MyNamespace.myFunction} 将以等宽字体呈现。

如果 templates.cleverLinks 为真，则忽略 templates.monospaceLinks。

相关链接

• 关于 JSDoc 插件
• JSDoc 的命令行参数
• 使用 Markdown 插件