用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
:一个可选的字符串,解释为一个正则表达式。如果存在的话,任何匹配这个正则表达式的文件将被忽略。默认设置是以下划线开头的文件(或以下划线开头的目录下的所有文件)将被忽略。
这些选项中使用的顺序是:
- 以命令行上给定的路径开始,并且在
source.include
中的所有文件(记得,使用-r
命令行选项将在子目录中搜索)。 - 对于在步骤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
部分设置成这样:
"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
原因如下:
- 根据
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
)
- 应用
source.includePattern
,剩下除了myProject/lib/d.txt
(因为它没有以.js
或.jsdoc
结束)以外的所有上述文件。 - 应用
source.excludePattern
,排除了myProject/\_private/a.js
。 - 应用
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: Closure Compiler 标签
默认情况下,两个词典都是启用的。此外,在默认情况下,jsdoc
字典首先被解析;作为一个结果,如果jsdoc
词典处理一个标签不同于closure
词典,jsdoc
版本的标签优先被采用(即,以jsdoc
版本的标签为准)。
如果您在Closure Compiler 项目中使用JSDoc,并且你想要避免使用 Closure Compiler无法识别的标签,更改tags.dictionaries
设置为[“closure”]。如果你想允许核心JSDoc标签, 但又想要确保Closure Compiler特定的标记使用Closure Compiler对其进行解释,您也可以更改此设置为[“closure”,”jsdoc”]。