forked from jsdoc/jsdoc.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathabout-configuring-jsdoc.html
359 lines (355 loc) · 18 KB
/
about-configuring-jsdoc.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
<!DOCTYPE html>
<!-- THIS IS A GENERATED FILE. DO NOT EDIT. -->
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="description" content="How to configure JSDoc using a configuration file.">
<title>Use JSDoc: Configuring JSDoc with a configuration file</title>
<link rel="stylesheet" href="styles/usejsdoc.css">
<link rel="stylesheet" href="styles/prettify.css">
<link rel="stylesheet" href="styles/css3-github-ribbon.css">
<script src="scripts/prettify.js"></script>
</head>
<body>
<header>
<a href="./index.html">@use JSDoc</a>
</header>
<article>
<h1>Configuring JSDoc with a configuration file</h1>
<h2>Table of Contents</h2>
<ul>
<li>
<a href="#configuration-file-formats">Configuration file formats</a>
</li>
<li>
<a href="#default-configuration-options">Default configuration options</a>
</li>
<li>
<a href="#configuring-plugins">Configuring plugins</a>
</li>
<li>
<a href="#specifying-recursion-depth">Specifying recursion depth</a>
</li>
<li>
<a href="#specifying-input-files">Specifying input files</a>
</li>
<li>
<a href="#specifying-the-source-type">Specifying the source type</a>
</li>
<li>
<a href="#incorporating-command-line-options-into-the-configuration-file">Incorporating command-line options into the configuration file</a>
</li>
<li>
<a href="#configuring-tags-and-tag-dictionaries">Configuring tags and tag dictionaries</a>
</li>
<li>
<a href="#configuring-templates">Configuring templates</a>
</li>
<li>
<a href="#related-links">Related Links</a>
</li>
</ul>
<h2 id="configuration-file-formats">Configuration file formats</h2>
<p>To customize JSDoc's behavior, you can provide a configuration file to JSDoc in one of the following
formats:</p>
<ul>
<li>A JSON file. In JSDoc 3.3.0 and later, this file may include comments.</li>
<li>A CommonJS module that exports a single configuration object. This format is supported in JSDoc</li>
</ul>
<p>3.5.0 and later.</p>
<p>To run JSDoc with a configuration file, use the <a href="about-commandline.html"><code>-c</code> command-line option</a> (for
example, <code>jsdoc -c /path/to/conf.json</code> or <code>jsdoc -c /path/to/conf.js</code>).</p>
<p>The following examples show a simple configuration file that enables JSDoc's <a href="plugins-markdown.html">Markdown
plugin</a>. JSDoc's configuration options are explained in detail in the following sections.</p>
<figure>
<figcaption>JSON configuration file</figcaption>
<pre class="prettyprint lang-js"><code>{
"plugins": ["plugins/markdown"]
}
</code></pre>
</figure>
<figure>
<figcaption>JavaScript configuration file</figcaption>
<pre class="prettyprint lang-js"><code>'use strict';
module.exports = {
plugins: ['plugins/markdown']
};
</code></pre>
</figure>
<p>For a more comprehensive example of a JSON configuration file, see the file
<a href="https://github.com/jsdoc3/jsdoc/blob/master/conf.json.EXAMPLE"><code>conf.json.EXAMPLE</code></a>.</p>
<h2 id="default-configuration-options">Default configuration options</h2>
<p>If you do not specify a configuration file, JSDoc uses the following configuration options:</p>
<figure>
<pre class="prettyprint lang-js"><code>{
"plugins": [],
"recurseDepth": 10,
"source": {
"includePattern": ".+\\.js(doc|x)?$",
"excludePattern": "(^|\\/|\\\\)_"
},
"sourceType": "module",
"tags": {
"allowUnknownTags": true,
"dictionaries": ["jsdoc","closure"]
},
"templates": {
"cleverLinks": false,
"monospaceLinks": false
}
}
</code></pre>
</figure>
<p>This means:</p>
<ul>
<li>No plugins are loaded (<code>plugins</code>).</li>
<li>If recursion is enabled with the <a href="about-commandline.html"><code>-r</code> command-line flag</a>, JSDoc will search
for files 10 levels deep (<code>recurseDepth</code>).</li>
<li>Only files ending in <code>.js</code>, <code>.jsdoc</code>, and <code>.jsx</code> will be processed (<code>source.includePattern</code>).</li>
<li>Any file starting with an underscore, or in a directory starting with an underscore, will be
ignored (<code>source.excludePattern</code>).</li>
<li>JSDoc supports code that uses <a href="howto-es2015-modules.html">ES2015 modules</a> (<code>sourceType</code>).</li>
<li>JSDoc allows you to use unrecognized tags (<code>tags.allowUnknownTags</code>).</li>
<li>Both standard JSDoc tags and <a
href="https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#jsdoc-tags">Closure Compiler tags</a> are enabled
(<code>tags.dictionaries</code>).</li>
<li><a href="tags-inline-link.html">Inline <code>{@link}</code> tags</a> are rendered in plain text (<code>templates.cleverLinks</code>,
<code>templates.monospaceLinks</code>).</li>
</ul>
<p>These options and others are explained in the following sections.</p>
<h2 id="configuring-plugins">Configuring plugins</h2>
<p>To enable plugins, add their paths (relative to the JSDoc folder) into the <code>plugins</code> array.</p>
<p>For example, the following JSON configuration file will enable the Markdown plugin, which converts
Markdown-formatted text to HTML, and the "summarize" plugin, which autogenerates a summary for each
doclet:</p>
<figure>
<figcaption>JSON configuration file with plugins</figcaption>
<pre class="prettyprint"><code>{
"plugins": [
"plugins/markdown",
"plugins/summarize"
]
}
</code></pre>
</figure>
<p>See the <a href="about-plugins.html">plugin reference</a> for further information, and look in <a
href="https://github.com/jsdoc3/jsdoc/tree/master/plugins">JSDoc's <code>plugins</code>
directory</a> for the plugins built into JSDoc.</p>
<p>You can configure the Markdown plugin by adding a <code>markdown</code> object to your configuration file. See
<a href="plugins-markdown.html">Configuring the Markdown Plugin</a> for details.</p>
<h2 id="specifying-recursion-depth">Specifying recursion depth</h2>
<p>The <code>recurseDepth</code> 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 <a href="about-commandline.html"><code>-r</code> command-line flag</a>, which tells JSDoc to recursively
search for input files.</p>
<figure>
<pre class="prettyprint lang-js"><code>{
"recurseDepth": 10
}
</code></pre>
</figure>
<h2 id="specifying-input-files">Specifying input files</h2>
<p>The <code>source</code> set of options, in combination with paths given to JSDoc on the command line,
determines the set of input files that JSDoc uses to generate documentation.</p>
<figure>
<pre class="prettyprint lang-js"><code>{
"source": {
"include": [ /* array of paths to files to generate documentation for */ ],
"exclude": [ /* array of paths to exclude */ ],
"includePattern": ".+\\.js(doc|x)?$",
"excludePattern": "(^|\\/|\\\\)_"
}
}
</code></pre>
</figure>
<ul>
<li><code>source.include</code>: An optional array of paths that contain files for which JSDoc should generate
documentation. The paths given to JSDoc on the command line are combined with these paths. You can
use the <a href="about-commandline.html"><code>-r</code> command-line option</a> to recurse into subdirectories.</li>
<li><code>source.exclude</code>: An optional array of paths that JSDoc should ignore. In JSDoc 3.3.0 and later,
this array may include subdirectories of the paths in <code>source.include</code>.</li>
<li><code>source.includePattern</code>: An optional string, interpreted as a regular expression. If present, all
filenames must match this regular expression to be processed by JSDoc. By default, this option is
set to ".+\.js(doc|x)?$", meaning that only files with the extensions <code>.js</code>, <code>.jsdoc</code>, and
<code>.jsx</code> will be processed.</li>
<li><code>source.excludePattern</code>: An optional string, interpreted as a regular expression. If present, any
file matching this regular expression will be ignored. By default, this option is set so that files
beginning with an underscore (or anything under a directory beginning with an underscore) is
ignored.</li>
</ul>
<p>These options are interpreted in the following order:</p>
<ol>
<li>Start with all paths given on the command line and in <code>source.include</code>.</li>
<li>For each file found in Step 1, if the regular expression <code>source.includePattern</code> is present, the
filename must match it, or it is ignored.</li>
<li>For each file left from Step 2, if the regular expression <code>source.excludePattern</code> is present, any
filename matching this regular expression is ignored.</li>
<li>For each file left from Step 3, if the file's path is in <code>source.exclude</code>, it is ignored.</li>
</ol>
<p>All remaining files after these four steps are processed by JSDoc.</p>
<p>As an example, suppose you have the following file structure:</p>
<figure>
<pre class="prettyprint"><code>myProject/
|- a.js
|- b.js
|- c.js
|- _private
| |- a.js
|- lib/
|- a.js
|- ignore.js
|- d.txt
</code></pre>
</figure>
<p>In addition, suppose your <code>conf.json</code> file looks like this example:</p>
<figure>
<pre class="prettyprint lang-js"><code>{
"source": {
"include": ["myProject/a.js", "myProject/lib", "myProject/_private"],
"exclude": ["myProject/lib/ignore.js"],
"includePattern": ".+\\.js(doc|x)?$",
"excludePattern": "(^|\\/|\\\\)_"
}
}
</code></pre>
</figure>
<p>If you run <code>jsdoc myProject/c.js -c /path/to/my/conf.json -r</code> from the file containing the
<code>myProject</code> folder, JSDoc will generate documentation for the following files:</p>
<ul>
<li><code>myProject/a.js</code></li>
<li><code>myProject/c.js</code></li>
<li><code>myProject/lib/a.js</code></li>
</ul>
<p>Here's why:</p>
<ol>
<li>Given <code>source.include</code> and the paths given on the command line, JSDoc starts off with these
files:<ul>
<li><code>myProject/c.js</code> (from the command line)</li>
<li><code>myProject/a.js</code> (from <code>source.include</code>)</li>
<li><code>myProject/lib/a.js</code>, <code>myProject/lib/ignore.js</code>, <code>myProject/lib/d.txt</code> (from <code>source.include</code>
and using the <code>-r</code> option)</li>
<li><code>myProject/_private/a.js</code> (from <code>source.include</code>)</li>
</ul>
</li>
<li>JSDoc applies <code>source.includePattern</code>, leaving us with all of the above files <em>except</em>
<code>myProject/lib/d.txt</code>, which does not end in <code>.js</code>, <code>.jsdoc</code>, or <code>.jsx</code>.</li>
<li>JSDoc applies <code>source.excludePattern</code>, which removes <code>myProject/_private/a.js</code>.</li>
<li>JSDoc applies <code>source.exclude</code>, which removes <code>myProject/lib/ignore.js</code>.</li>
</ol>
<h2 id="specifying-the-source-type">Specifying the source type</h2>
<p>The <code>sourceType</code> 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:</p>
<ul>
<li><code>module</code> (default): Use this value for most types of JavaScript files.</li>
<li><code>script</code>: Use this value if JSDoc logs errors such as <code>Delete of an unqualified identifier in
strict mode</code> when it parses your code.</li>
</ul>
<figure>
<pre class="prettyprint lang-js"><code>{
"sourceType": "module"
}
</code></pre>
</figure>
<h2 id="incorporating-command-line-options-into-the-configuration-file">Incorporating command-line options into the configuration file</h2>
<p>You can put many of JSDoc's <a href="about-commandline.html">command-line options</a> into the configuration file instead of
specifying them on the command line. To do this, add the long names of the relevant options into an
<code>opts</code> section of the configuration file, with the value set to the option's value.</p>
<figure>
<figcaption>JSON configuration file with command-line options</figcaption>
<pre class="prettyprint lang-js"><code>{
"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
}
}
</code></pre>
</figure>
<p>By using the <code>source.include</code> and <code>opts</code> options, you can put almost all of the arguments to JSDoc
in a configuration file, so that the command line reduces to:</p>
<pre class="prettyprint"><code>jsdoc -c /path/to/conf.json
</code></pre>
<p>When options are specified on the command line <em>and</em> in the configuration file, the command line
takes precedence.</p>
<h2 id="configuring-tags-and-tag-dictionaries">Configuring tags and tag dictionaries</h2>
<p>The options in <code>tags</code> control which JSDoc tags are allowed and how each tag is interpreted.</p>
<figure>
<pre class="prettyprint lang-js"><code>{
"tags": {
"allowUnknownTags": true,
"dictionaries": ["jsdoc","closure"]
}
}
</code></pre>
</figure>
<p>The <code>tags.allowUnknownTags</code> property affects how JSDoc handles unrecognized tags. If you set this
option to <code>false</code>, and JSDoc finds a tag that it does not recognize (for example, <code>@foo</code>), JSDoc
logs a warning. By default, this option is set to <code>true</code>. 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, <code>["foo","bar"]</code>).</p>
<p>The <code>tags.dictionaries</code> 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:</p>
<ul>
<li><code>jsdoc</code>: Core JSDoc tags.</li>
<li><code>closure</code>: <a href="https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#jsdoc-tags">Closure
Compiler tags</a>.</li>
</ul>
<p>By default, both dictionaries are enabled. Also, by default, the <code>jsdoc</code> dictionary is listed first;
as a result, if the <code>jsdoc</code> dictionary handles a tag differently than the <code>closure</code> dictionary, the
<code>jsdoc</code> version of the tag takes precedence.</p>
<p>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 <code>tags.dictionaries</code> setting to <code>["closure"]</code>. You
can also change this setting to <code>["closure","jsdoc"]</code> 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.</p>
<h2 id="configuring-templates">Configuring templates</h2>
<p>The options in <code>templates</code> affect the appearance and content of generated documentation. Third-party
templates may not implement all of these options. See <a href="about-configuring-default-template.html">Configuring JSDoc's Default
Template</a> for additional options that the default template supports.</p>
<figure>
<pre class="prettyprint lang-js"><code>{
"templates": {
"cleverLinks": false,
"monospaceLinks": false
}
}
</code></pre>
</figure>
<p>If <code>templates.monospaceLinks</code> is true, all link text from the <a href="tags-inline-link.html">inline <code>{@link}</code>
tag</a> will be rendered in monospace.</p>
<p>If <code>templates.cleverLinks</code> is true, <code>{@link asdf}</code> will be rendered in normal font if <code>asdf</code> is a
URL, and monospace otherwise. For example, <code>{@link http://github.com}</code> will render in plain text,
but <code>{@link MyNamespace.myFunction}</code> will be in monospace.</p>
<p>If <code>templates.cleverLinks</code> is true, <code>templates.monospaceLinks</code> is ignored.</p>
<h2 id="related-links">Related Links</h2>
<ul>
<li>
<a href="about-commandline.html">Command-line arguments to JSDoc</a>
</li>
<li>
<a href="about-plugins.html">About JSDoc plugins</a>
</li>
<li>
<a href="plugins-markdown.html">Using the Markdown plugin</a>
</li>
</ul>
</article>
<footer>
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" /></a>
<br>
Copyright © 2011-2017 the
<a href="https://github.com/jsdoc3/jsdoc3.github.com/contributors">contributors</a> to the
JSDoc 3 documentation project.
<br>
This website is <a href="https://github.com/jsdoc3/jsdoc3.github.com">open source</a> and is
licensed under the <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
</footer>
<script type="text/javascript">
prettyPrint();
</script>
</body>
</html>