用conf.json配置JSDoc

Configuration File(配置文件)

要自定义JSDoc的行为，可以使用JSON格式的配置文件格式化JSDoc，使用-c选项，例如： jsdoc -c /path/to/conf.json。

这个文件（通常命名为conf.json）提供了JSON格式化选项。看看JSDoc目录中的一个基本的例子conf.json.EXAMPLE。如果不指定配置文件，这是JSDoc将会使用什么：

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

这意味着：

  • JSDoc允许您使用无法识别的标签（tags.allowUnknownTags）;
  • 这两个标准JSDoc标签和closure标签被启用（tags.dictionaries）;
  • 只有以.js和.jsdoc结尾的文件将会被处理（source.includePattern）;
  • 任何文件以下划线开始或开始下划线的目录都将被忽略（source.excludePattern）;
  • 无插件加载（plugins）;
  • @link标签呈现在纯文本（templates.cleverLinks，templates.monospaceLinks）。

这些选项和其他选项将在这个页面中进一步解释。

各种插件或模板等进一步设置可被添加到该文件（例如，markdown插件可以通过markdown key进行配置）。

Specifying input files(指定输入文件)

source选项组，结合给JSDoc命令行的路径，确定哪些文件要用JSDoc生成文档。 （在添加这个例子到你自己的.json文件之前，请先删除注释。）

"source": {
    "include": [ /* array of paths to files to generate documentation for */ ],
    "exclude": [ /* array of paths to exclude */ ],
    "includePattern": ".+\\.js(doc)?$",
    "excludePattern": "(^|\\/|\\\\)_"
}
  • source.include：可选的路径数组，JSDoc应该为它们生成文档。JSDoc将会结合命令行上的路径和这些文件名，以形成文件组，并且扫描。如果路径是一个目录，可以使用-r选项来递归。
  • source.exclude：可选的路径数组，JSDoc应该忽略的路径。在JSDoc3.3.0或更高版本，该数组可包括source.include路径中的子目录。
  • source.includePattern：一个可选的字符串，解释为一个正则表达式。如果存在，所有文件必须匹配这个正则表达式，以通过JSDoc进行扫描。默认情况下此选项设置为.+.js(doc)?$，这意味着只有以.js或者.jsdoc结尾的文件将被扫描。
  • source.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)?$",
    "excludePattern": "(^|\\/|\\\\)_"
}

如果我从包含在myProject文件夹中的文件运行JSDoc，像这样：

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和命令行中给定的路径，我们开始扫描文件
    • 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. 应用source.includePattern，剩下除了myProject/lib/d.txt（因为它没有以.js或.jsdoc结束）以外的所有上述文件。
  3. 应用source.excludePattern，排除了myProject/\_private/a.js。
  4. 应用source.exclude，排除了myProject/lib/ignore.js。

Incorporating command-line options into the configuration file(合并命令行选项到配置文件)

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

在配置文件中设置的命令行选项

"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中提供的选项。

Plugins（插件）

要启用插件，只要添加它们的路径（相对于JSDoc文件夹）到plugins数组中就可以了。

例如，以下将包括 markdown 插件，它转换 markdown格式的文本为HTML，和“summarize”插件，该自动生成的每个的doclet的摘要：

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

更多信息请参见插件参考，并在jsdoc/plugins 中查找插件 来构建JSDoc。

markdown插件可以通过在conf.json中设置markdown对象进行配置;请参阅配置markdown插件获得更多信息。

Output style configuration(配置输出风格)

templates选项会影响外观和生成的文档内容。自定义模板可能不会实现所有的选项。请参阅配置JSDoc的默认模板中默认模板支持的附加选项。

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

如果templates.monospaceLinks为true，从@link标签生成的所有链接文本将会以等宽字体渲染。

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

如果templates.cleverLinks为true，它是引用,并且templates.monospaceLinks是被忽略的。

另外，还有一些{@linkcode…}和{@linkplain…},如果希望强制的链接被等宽或普通字体分别渲染（见@link，@linkcode和@linkplain了解更多信息）。

Tags and tag dictionaries(标签和标签字典)

tags选项控制哪些JSDoc标签允许被使用和解析。

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

tags.allowUnknownTags属性影响JSDoc如何处理无法识别的标签。如果将此选项设置为false，JSDoc发现它不能识别（例如,@foo），JSDoc将记录一个警告。默认情况下，此选项设置为true。

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

默认情况下，两个词典都是启用的。此外，在默认情况下，jsdoc字典首先被解析;作为一个结果，如果jsdoc词典处理一个标签不同于closure词典，jsdoc版本的标签优先被采用(即，以jsdoc版本的标签为准)。

如果您在Closure Compiler 项目中使用JSDoc，并且你想要避免使用 Closure Compiler无法识别的标签，更改tags.dictionaries设置为[“closure”]。如果你想允许核心JSDoc标签, 但又想要确保Closure Compiler特定的标记使用Closure Compiler对其进行解释，您也可以更改此设置为[“closure”,”jsdoc”]。