配置JSDoc用conf.json

原文：http://usejsdoc.org/about-configuring-jsdoc.html
配置文件

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

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

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

这意味着：

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

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

所要求的各种插件或模板，进一步设置可被添加到该文件（例如，markdown插件可以通过包括“markdown”key 配置）。

指定输入文件

选项组“源”，结合给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在命令行上的与这些形成集文件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": {    "include": [ "myProject/a.js", "myProject/lib", "myProject/_private" ],    "exclude": [ "myProject/lib/ignore.js" ],    "includePattern": ".+\\.js(doc)?$",    "excludePattern": "(^|\\/|\\\\)_"}

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

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 and 使用 -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。

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

它有可能把许多JSDoc的命令行选项放到配置文件，代替在命令行中指定它们。要做到这一点，使用相关选项的长名称在一个conf.json的“opts”区域中的值是该选项的值。

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

"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中，在命令行中优先。

插件

要启用插件，增加它们的路径（相对于JSDoc文件夹）到plugins数组。

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

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

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

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

输出风格的配置

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

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

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

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

如果templates.cleverLinks是true，它是引用和templates.monospaceLinks是被忽略的。

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

标签和标签字典

在标签上的选项控制，JSDoc标签是允许的，并且每个标签是怎么解释的。

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

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

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

• jsdoc: Core JSDoc tags.
• closure: Closure Compiler tags.（关闭编译器标签）

默认情况下，词典启用。此外，在默认情况下，该jsdoc字典列在第一位;作为一个结果，如果jsdoc词典处理一个标签不同于关闭词典，标签jsdoc的版本优先。

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