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。

🌐 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” 插件，该插件会为每个文档块自动生成摘要：

🌐 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 命令行标志 时才使用此选项，-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 中给出的所有路径开始。
  2. 对于在步骤1中找到的每个文件，如果存在正则表达式 source.includePattern，则文件名必须与之匹配，否则将被忽略。
  3. 对于第2步剩下的每个文件，如果存在正则表达式 source.excludePattern，则任何匹配该正则表达式的文件名都会被忽略。
  4. 对于步骤3中剩下的每个文件，如果文件的路径在source.exclude中，则忽略该文件。

这四个步骤之后剩下的所有文件都由 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 从这些文件开始： + 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。

指定源类型

🌐 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.

如果你在使用带有 Closure Compiler 的 JSDoc 项目，并且想要避免使用 Closure Compiler 无法识别的标签，请将 tags.dictionaries 设置更改为 ["closure"]。如果你想允许使用核心 JSDoc 标签，但又希望确保 Closure Compiler 特定的标签按 Closure Compiler 的方式进行解释，也可以将该设置更改为 ["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 为真，来自 内联 {@link} 标签 的所有链接文本将以等宽字体呈现。

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

如果 templates.cleverLinks 为真，当 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.