JSDoc 中文网

使用配置文件配置 JSDoc

配置文件格式

¥Configuration file formats

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

¥To customize JSDoc's behavior, you can provide a configuration file to JSDoc in one of the following formats:

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

¥To run JSDoc with a configuration file, use the -c command-line option (for example, jsdoc -c /path/to/conf.json or jsdoc -c /path/to/conf.js).

以下示例显示了启用 JSDoc 的 Markdown 插件 的简单配置文件。JSDoc 的配置选项将在以下部分详细解释。

¥The following examples show a simple configuration file that enables JSDoc's Markdown plugin. JSDoc's configuration options are explained in detail in the following sections.

JSON 配置文件
{
    "plugins": ["plugins/markdown"]
}
JavaScript 配置文件
'use strict';

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

有关 JSON 配置文件的更全面的示例，请参阅文件 conf.json.EXAMPLE.json。

¥For a more comprehensive example of a JSON configuration file, see the file conf.json.EXAMPLE.

默认配置选项

¥Default configuration options

如果不指定配置文件，JSDoc 将使用以下配置选项：

¥If you do not specify a configuration file, JSDoc uses the following configuration options:

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

这意味着：

¥This means:

这些选项和其他选项将在以下部分中进行解释。

¥These options and others are explained in the following sections.

配置插件

¥Configuring plugins

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

¥To enable plugins, add their paths (relative to the JSDoc folder) into the plugins array.

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

¥For example, the following JSON configuration file will enable the Markdown plugin, which converts Markdown-formatted text to HTML, and the "summarize" plugin, which autogenerates a summary for each doclet:

带有插件的 JSON 配置文件
{
    "plugins": [
        "plugins/markdown",
        "plugins/summarize"
    ]
}

请参阅 插件参考 以获取更多信息，并在 JSDoc 的 plugins 目录 中查找 JSDoc 中内置的插件。

¥See the plugin reference for further information, and look in JSDoc's plugins directory for the plugins built into JSDoc.

你可以通过将 markdown 对象添加到配置文件来配置 Markdown 插件。详情请参见 配置 Markdown 插件。

¥You can configure the Markdown plugin by adding a markdown object to your configuration file. See Configuring the Markdown Plugin for details.

指定递归深度

¥Specifying recursion depth

recurseDepth 选项控制 JSDoc 将递归搜索源文件和教程的深度。此选项在 JSDoc 3.5.0 及更高版本中可用。仅当你还指定 -r 命令行标志 时才使用此选项，它告诉 JSDoc 递归搜索输入文件。

¥The recurseDepth option controls how many levels deep JSDoc will recursively search for source files and tutorials. This option is available in JSDoc 3.5.0 and later. This option is used only if you also specify the -r command-line flag, which tells JSDoc to recursively search for input files.

{
    "recurseDepth": 10
}

指定输入文件

¥Specifying input files

source 选项集与命令行上给 JSDoc 的路径相结合，确定 JSDoc 用于生成文档的输入文件集。

¥The source set of options, in combination with paths given to JSDoc on the command line, determines the set of input files that JSDoc uses to generate documentation.

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

这些选项按以下顺序解释：

¥These options are interpreted in the following order:

  1. 从命令行和 source.include 中给出的所有路径开始。

    ¥Start with all paths given on the command line and in source.include.

  2. 对于步骤 1 中找到的每个文件，如果存在正则表达式 source.includePattern，则文件名必须与其匹配，否则将被忽略。

    ¥For each file found in Step 1, if the regular expression source.includePattern is present, the filename must match it, or it is ignored.

  3. 对于步骤 2 留下的每个文件，如果存在正则表达式 source.excludePattern，则忽略与此正则表达式匹配的任何文件名。

    ¥For each file left from Step 2, if the regular expression source.excludePattern is present, any filename matching this regular expression is ignored.

  4. 对于步骤 3 留下的每个文件，如果该文件的路径位于 source.exclude 中，则将忽略该文件。

    ¥For each file left from Step 3, if the file's path is in source.exclude, it is ignored.

这四个步骤之后剩下的所有文件都由 JSDoc 处理。

¥All remaining files after these four steps are processed by JSDoc.

例如，假设你有以下文件结构：

¥As an example, suppose you have the following file structure:

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

此外，假设你的 conf.json 文件如下例所示：

¥In addition, suppose your conf.json file looks like this example:

{
    "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 将为以下文件生成文档：

¥If you run jsdoc myProject/c.js -c /path/to/my/conf.json -r from the file containing the myProject folder, JSDoc will generate documentation for the following files:

原因如下：

¥Here's why:

  1. 给定 source.include 和命令行上给出的路径，JSDoc 从以下文件开始：

    ¥Given source.include and the paths given on the command line, JSDoc starts off with these files:

    • myProject/c.js（从命令行）

      ¥myProject/c.js (from the command line)

    • myProject/a.js（自 source.include 起）

      ¥myProject/a.js (from source.include)

    • myProject/lib/a.js、myProject/lib/ignore.js、myProject/lib/d.txt（从 source.include 开始并使用 -r 选项）

      ¥myProject/lib/a.js, myProject/lib/ignore.js, myProject/lib/d.txt (from source.include and using the -r option)

    • myProject/_private/a.js（自 source.include 起）

      ¥myProject/_private/a.js (from source.include)

  2. JSDoc 应用 source.includePattern，给我们留下除 myProject/lib/d.txt 之外的所有上述文件，myProject/lib/d.txt 不以 .js、.jsdoc 或 .jsx 结尾。

    ¥JSDoc applies source.includePattern, leaving us with all of the above files except myProject/lib/d.txt, which does not end in .js, .jsdoc, or .jsx.

  3. JSDoc 应用 source.excludePattern，从而删除 myProject/_private/a.js。

    ¥JSDoc applies source.excludePattern, which removes myProject/_private/a.js.

  4. JSDoc 应用 source.exclude，从而删除 myProject/lib/ignore.js。

    ¥JSDoc applies source.exclude, which removes myProject/lib/ignore.js.

指定源类型

¥Specifying the source type

sourceType 选项影响 JSDoc 解析 JavaScript 文件的方式。此选项在 JSDoc 3.5.0 及更高版本中可用。该选项接受以下值：

¥The sourceType option affects how JSDoc parses your JavaScript files. This option is available in JSDoc 3.5.0 and later. This option accepts the following values:

{
    "sourceType": "module"
}

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

¥Incorporating command-line options into the configuration file

你可以把很多 JSDoc 的 命令行选项 放到配置文件中，而不用在命令行上指定。为此，请将相关选项的长名称添加到配置文件的 opts 部分，并将值设置为选项的值。

¥You can put many of JSDoc's command-line options into the configuration file instead of specifying them on the command line. To do this, add the long names of the relevant options into an opts section of the configuration file, with the value set to the option's value.

带有命令行选项的 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 的几乎所有参数放入配置文件中，以便命令行减少为：

¥By using the source.include and opts options, you can put almost all of the arguments to JSDoc in a configuration file, so that the command line reduces to:

jsdoc -c /path/to/conf.json

当在命令行和配置文件中指定选项时，命令行优先。

¥When options are specified on the command line and in the configuration file, the command line takes precedence.

配置标签和标签字典

¥Configuring tags and tag dictionaries

tags 中的选项控制允许哪些 JSDoc 标记以及如何解释每个标记。

¥The options in tags control which JSDoc tags are allowed and how each tag is interpreted.

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

tags.allowUnknownTags 属性影响 JSDoc 处理无法识别标签的方式。如果将此选项设置为 false，并且 JSDoc 发现它无法识别的标签（例如 @foo），JSDoc 会记录一条警告。默认情况下，此选项设置为 true。在 JSDoc 3.4.1 及更高版本中，你还可以将此属性设置为 JSDoc 应允许的标记名称数组（例如，["foo","bar"]）。

¥The tags.allowUnknownTags property affects how JSDoc handles unrecognized tags. If you set this option to false, and JSDoc finds a tag that it does not recognize (for example, @foo), JSDoc logs a warning. By default, this option is set to true. In JSDoc 3.4.1 and later, you can also set this property to an array of tag names that JSDoc should allow (for example, ["foo","bar"]).

tags.dictionaries 属性控制 JSDoc 识别哪些标签，以及 JSDoc 如何解释它识别的标签。在 JSDoc 3.3.0 及更高版本中，有两个内置标签字典：

¥The tags.dictionaries property controls which tags JSDoc recognizes, as well as how JSDoc interprets the tags that it recognizes. In JSDoc 3.3.0 and later, there are two built-in tag dictionaries:

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

¥By default, both dictionaries are enabled. Also, by default, the jsdoc dictionary is listed first; as a result, if the jsdoc dictionary handles a tag differently than the closure dictionary, the jsdoc version of the tag takes precedence.

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

¥If you are using JSDoc with a Closure Compiler project, and you want to avoid using tags that Closure Compiler does not recognize, change the tags.dictionaries setting to ["closure"]. You can also change this setting to ["closure","jsdoc"] if you want to allow core JSDoc tags, but you want to ensure that Closure Compiler-specific tags are interpreted as Closure Compiler would interpret them.

配置模板

¥Configuring templates

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

¥The options in templates affect the appearance and content of generated documentation. Third-party templates may not implement all of these options. See Configuring JSDoc's Default Template for additional options that the default template supports.

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

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

¥If templates.monospaceLinks is true, all link text from the inline {@link} tag will be rendered in monospace.

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

¥If templates.cleverLinks is true, {@link asdf} will be rendered in normal font if asdf is a URL, and monospace otherwise. For example, {@link http://github.com} will render in plain text, but {@link MyNamespace.myFunction} will be in monospace.

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

¥If templates.cleverLinks is true, templates.monospaceLinks is ignored.