使用配置文件配置JSDoc¶

配置文件格式¶

要自定义JSDoc的行为, 您可以使用以下格式之一为JSDoc提供配置文件:

一个JSON文件. 在JSDoc 3.3.0及更高版本中, 此文件可能包含注释.
用于导出单个配置对象的CommonJS模块. JSDoc 3.5.0及更高版本支持此格式.

To run JSDoc with a configuration file, use the -c JSDoc的命令行参数 (for example, jsdoc -c /path/to/conf.json or jsdoc -c /path/to/conf.js).

The following examples show a simple configuration file that enables JSDoc’s markdown插件. JSDoc’s configuration options are explained in detail in the following sections.

JSON configuration file¶

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

JavaScript configuration file¶

'use strict';

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

For a more comprehensive example of a JSON configuration file, see the file 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).
If recursion is enabled with the -r JSDoc的命令行参数, JSDoc will search for files 10 levels deep (recurseDepth).
只处理以 .js, .jsdoc 和 .jsx 结尾的文件(source.includePattern).
任何以下划线开头的文件或以下划线开头的目录都将被忽略(source.excludePattern).
JSDoc supports code that uses ECMAScript 2015模块 (sourceType).
JSDoc允许您使用无法识别的标签(tags.allowUnknownTags).
Both standard JSDoc tags and Closure Compiler tags are enabled (tags.dictionaries).
Inline {@link} are rendered in plain text (templates.cleverLinks, templates.monospaceLinks).

以下各节将介绍这些选项和其他选项.

配置插件¶

要启用插件, 请将它们的路径(相对于JSDoc文件夹)添加到 plugins 数组中.

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 configuration file with plugins¶

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

See the 关于JSDoc插件 for further information, and look in JSDoc’s plugins directory for the plugins built into JSDoc.

You can configure the Markdown plugin by adding a markdown object to your configuration file. See markdown插件 for details.

指定递归深度¶

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 JSDoc的命令行参数, which tells JSDoc to recursively search for input files.

{
    "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: An optional array of paths that contain files for which JSDoc should generate documentation. The paths given to JSDoc on the command line are combined with these paths. You can use the -r JSDoc的命令行参数 to recurse into subdirectories.
source.exclude: JSDoc应忽略的可选路径数组. 在JSDoc 3.3.0及更高版本中, 此数组可能包含 source.include 中路径的子目录.
source.includePattern: An optional string, interpreted as a regular expression. If present, all filenames must match this regular expression to be processed by JSDoc. By default, this option is set to “.+.js(doc|x)?$”, meaning that only files with the extensions .js, .jsdoc, and .jsx will be processed.
source.excludePattern: 可选字符串, 解释为正则表达式. 如果存在, 则将忽略与此正则表达式匹配的任何文件. 默认情况下, 设置此选项以便忽略以下划线开头的文件(或以下划线开头的任何内容下的任何内容).

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

从命令行和 source.include 中给出的所有路径开始.
对于步骤1中找到的每个文件, 如果存在正则表达式 source.includePattern , 则文件名必须与之匹配, 否则将被忽略.
对于步骤2中剩下的每个文件, 如果存在正则表达式 source.excludePattern , 则忽略与该正则表达式匹配的任何文件名.
对于步骤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": "(^|\\/|\\\\)_"
    }
}

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:

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

这就是原因:

给定 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)
JSDoc应用``source.includePattern``, 留下我们所有的上述文件除了 myProject/lib/d.txt, 它不以 .js, .jsdoc 结尾, 或 .jsx.
JSDoc应用``source.excludePattern``, 删除 myProject/_private/a.js.
JSDoc应用 source.exclude, 删除 myProject/lib/ignore.js.

指定源类型¶

``sourceType``选项影响JSDoc解析JavaScript文件的方式. JSDoc 3.5.0及更高版本中提供了此选项. 此选项接受以下值:

module (default): 将此值用于大多数类型的JavaScript文件.
script: 如果JSDoc在解析代码时记录诸如 `在严格模式下删除非限定标识符 `之类的错误, 则使用此值.

{
    "sourceType": "module"
}

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

You can put many of JSDoc’s JSDoc的命令行参数 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 configuration file with command-line options¶

{
    "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"]
    }
}

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及更高版本中, 有两个内置标记字典:

jsdoc: 核心JSDoc标签.
closure: Closure Compiler tags.

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

如果您正在使用带有Closure Compiler项目的JSDoc, 并且您想避免使用Closure Compiler无法识别的标记, 请将 tags.dictionaries 设置更改为 ["closure"]. 您还可以将此设置更改为 ["closure","jsdoc"] 如果您想允许核心JSDoc标记, 但是您希望确保将Closure Compiler特定的标记解释为Closure Compiler解释他们.

配置模板¶

The options in templates affect the appearance and content of generated documentation. Third-party templates may not implement all of these options. See 配置JSDoc的默认模板 for additional options that the default template supports.

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

If templates.monospaceLinks is true, all link text from the inline will be rendered in monospace.

如果 templates.cleverLinks 为真, 如果 asdf 是一个URL, 则 {@link asdf} 将以普通字体呈现, 否则为monospace. 例如, {@link http://github.com} 将以纯文本形式呈现, 但 {@link MyNamespace.myFunction} 将是等宽的.

如果 templates.cleverLinks 为真, 则忽略 templates.monospaceLinks.