JSDoc中文文档(@use JSDoc)

使用配置文件配置JSDoc

目录

配置文件格式

To customize JSDoc's behavior, you can provide a configuration file to JSDoc in one of the following formats: 要自定义JSDoc的行为，可以使用下面格式的配置文件

在运行JSDoc时指定配置文件，使用[-c命令行选项][about-commadline]即可。（例如 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指定配置文件，那么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-formatterd文本转换为HTML）和"summarzie"插件（自动为每个Doclet生成总结）

示例: JSON 插件配置
{
    "plugins": [
        "plugins/markdown",
        "plugins/summarize"
    ]
}

查看 插件手册页 获取更多信息, 并且查看 JSDoc's plugins 目录 获取JSDoc的内建插件。

你可通过在配置文件中添加markdown对象来配置Markdown插件，更多信息请查看配置Markdown插件。

指定递归深度

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
}

指定输入文件

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中的所有文件（记得，使用-r命令行选项将在子目录中搜索）。

  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部分设置成这样：

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

如果我从包含在myProject文件夹中的文件运行JSDoc，像这样： jsdoc myProject/c.js -c /path/to/my/conf.json -r

然后JSDoc会为这些文件生产文档：

原因如下:

  1. 根据source.include和命令行中给定的路径，我们开始扫描文件
    • 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, or .jsx结尾）以外的所有文件。
  3. JSDoc 应用 source.excludePattern, 将移除 myProject/_private/a.js.
  4. JSDoc 应用 source.exclude, 将移除 myProject/lib/ignore.js.

Specifying the source type

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

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

你可以把许多JSDoc的命令行选项放到配置文件，而不用在命令行中指定它们。要做到这一点，只要在conf.json的opts部分中使用的相关选项的longnames,值是该选项的值。

示例: 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

在命令行中所提供的选项 优先级高于在conf.json中提供的选项。

Configuring tags and tag dictionaries

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

{
    "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"]).

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:

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.

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

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

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

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.

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