用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.cleverLinkstemplates.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.jsonopts部分中使用的相关选项的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.includeopts,把所有的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.monospaceLinkstrue,从@link标签生成的所有链接文本将会以等宽字体渲染。

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

如果templates.cleverLinkstrue,它是引用,并且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”]。