10000 reorder sections; document recurseDepth config option (#165) · edbrannin/jsdoc.github.io@b171945 · GitHub
[go: up one dir, main page]
Skip to content

Commit b171945

Browse files
hegemonichegemonic
committed
reorder sections; document recurseDepth config option (jsdoc#165)
1 parent 165a087 commit b171945

File tree

2 files changed

+138
-102
lines changed

2 files changed

+138
-102
lines changed

‎about-configuring-jsdoc.html

Lines changed: 55 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -31,19 +31,22 @@ <h2>Table of Contents</h2>
3131
<a href="#default-configuration-options">Default configuration options</a>
3232
</li>
3333
<li>
34-
<a href="#specifying-input-files">Specifying input files</a>
34+
<a href="#configuring-plugins">Configuring plugins</a>
3535
</li>
3636
<li>
37-
<a href="#incorporating-command-line-options-into-the-configuration-file">Incorporating command-line options into the configuration file</a>
37+
<a href="#specifying-recursion-depth">Specifying recursion depth</a>
38+
</li>
39+
<li>
40+
<a href="#specifying-input-files">Specifying input files</a>
3841
</li>
3942
<li>
40-
<a href="#plugins">Plugins</a>
43+
<a href="#incorporating-command-line-options-into-the-configuration-file">Incorporating command-line options into the configuration file</a>
4144
</li>
4245
<li>
43-
<a href="#template-configuration">Template configuration</a>
46+
<a href="#configuring-tags-and-tag-dictionaries">Configuring tags and tag dictionaries</a>
4447
</li>
4548
<li>
46-
<a href="#tags-and-tag-dictionaries">Tags and tag dictionaries</a>
49+
<a href="#configuring-templates">Configuring templates</a>
4750
</li>
4851
<li>
4952
<a href="#related-links">Related Links</a>
@@ -79,6 +82,7 @@ <h2 id="default-configuration-options">Default configuration options</h2>
7982
<p>If you do not specify a configuration file, JSDoc uses the following configuration options:</p>
8083
<figure><pre class="prettyprint lang-js"><code>{
8184
"plugins": [],
85+
"recurseDepth": 10,
8286
"source": {
8387
"includePattern": ".+\\.js(doc|x)?$",
8488
"excludePattern": "(^|\\/|\\\\)_"
@@ -97,6 +101,7 @@ <h2 id="default-configuration-options">Default configuration options</h2>
97101
<p>This means:</p>
98102
<ul>
99103
<li>No plugins are loaded (<code>plugins</code>).</li>
104+
<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>
100105
<li>Only files ending in <code>.js</code>, <code>.jsdoc</code>, and <code>.jsx</code> will be processed (<code>source.includePattern</code>).</li>
101106
<li>Any file starting with an underscore, or in a directory starting with an underscore, will be ignored (<code>source.excludePattern</code>).</li>
102107
<li>JSDoc allows you to use unrecognized tags (<code>tags.allowUnknownTags</code>).</li>
@@ -106,6 +111,33 @@ <h2 id="default-configuration-options">Default configuration options</h2>
106111
<code>templates.monospaceLinks</code>).</li>
107112
</ul>
108113
<p>These options and others are explained in the following sections.</p>
114+
<h2 id="configuring-plugins">Configuring plugins</h2>
115+
<p>To enable plugins, add their paths (relative to the JSDoc folder) into the <code>plugins</code> array.</p>
116+
<p>For example, the following JSON configuration file will enable the Markdown plugin, which converts Markdown-formatted text to HTML, and the &quot;summarize&quot;
117+
plugin, which autogenerates a summary for each doclet:
118+
</p>
119+
<figure>
120+
<figcaption>JSON configuration file with plugins</figcaption><pre class="prettyprint"><code>{
121+
"plugins": [
122+
"plugins/markdown",
123+
"plugins/summarize"
124+
]
125+
}
126+
</code></pre>
127+
</figure>
128+
<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&#39;s <code>plugins</code>
129+
directory</a> for the plugins built into JSDoc.</p>
130+
<p>You can configure the Markdown plugin by adding a <code>markdown</code> object to your configuration file. See
131+
<a href="plugins-markdown.html">Configuring the Markdown Plugin</a> for details.</p>
132+
<h2 id="specifying-recursion-depth">Specifying recursion depth</h2>
133+
<p>The <code>recurseDepth</code> option controls how many levels deep JSDoc will recursively search for source files and tutorials. This option is used only if
134+
you also specify the <a href="about-commandline.html"><code>-r</code> command-line
135+
flag</a>, which tells JSDoc to recursively search for input files.</p>
136+
<figure><pre class="prettyprint lang-js"><code>{
137+
"recurseDepth": 10
138+
}
139+
</code></pre>
140+
</figure>
109141
<h2 id="specifying-input-files">Specifying input files</h2>
110142
<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
111143
documentation.</p>
@@ -211,42 +243,7 @@ <h2 id="incorporating-command-line-options-into-the-configuration-file">Incorpor
211243
<pre class="prettyprint"><code>jsdoc -c /path/to/conf.json
212244
</code></pre>
213245
<p>When options are specified on the command line <em>and</em> in the configuration file, the command line takes precedence.</p>
214-
<h2 id="plugins">Plugins</h2>
215-
<p>To enable plugins, add their paths (relative to the JSDoc folder) into the <code>plugins</code> array.</p>
216-
<p>For example, the following JSON configuration file will enable the Markdown plugin, which converts Markdown-formatted text to HTML, and the &quot;summarize&quot;
217-
plugin, which autogenerates a summary for each doclet:
218-
</p>
219-
<figure>
220-
<figcaption>JSON configuration file with plugins</figcaption><pre class="prettyprint"><code>{
221-
"plugins": [
222-
"plugins/markdown",
223-
"plugins/summarize"
224-
]
225-
}
226-
</code></pre>
227-
</figure>
228-
<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&#39;s <code>plugins</code>
229-
directory</a> for the plugins built into JSDoc.</p>
230-
<p>You can configure the Markdown plugin by adding a <code>markdown</code> object to your configuration file. See
231-
<a href="plugins-markdown.html">Configuring the Markdown Plugin</a> for details.</p>
232-
<h2 id="template-configuration">Template configuration</h2>
233-
<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.
234-
See <a href="about-configuring-default-template.html">Configuring JSDoc&#39;s Default
235-
Template</a> for additional options that the default template supports.</p>
236-
<figure><pre class="prettyprint lang-js"><code>{
237-
"templates": {
238-
"cleverLinks": false,
239-
"monospaceLinks": false
240-
}
241-
}
242-
</code></pre>
243-
</figure>
244-
<p>If <code>templates.monospaceLinks</code> is true, all link text from the <a href="tags-inline-link.html">inline <code>{@link}</code>
245-
tag</a> will be rendered in monospace.</p>
246-
<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.
247-
For example, <code>{@link http://github.com}</code> will render in plain text, but <code>{@link MyNamespace.myFunction}</code> will be in monospace.</p>
248-
<p>If <code>templates.cleverLinks</code> is true, <code>templates.monospaceLinks</code> is ignored.</p>
249-
<h2 id="tags-and-tag-dictionaries">Tags and tag dictionaries</h2>
246+
<h2 id="configuring-tags-and-tag-dictionaries">Configuring tags and tag dictionaries</h2>
250247
<p>The options in <code>tags</code> control which JSDoc tags are allowed and how each tag is interpreted.</p>
251248
<figure><pre class="prettyprint lang-js"><code>{
252249
"tags": {
@@ -271,6 +268,23 @@ <h2 id="tags-and-tag-dictionaries">Tags and tag dictionaries</h2>
271268
<code>jsdoc</code> version of the tag takes precedence.</p>
272269
<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>[&quot;closure&quot;]</code>. You can also change this setting to <code>[&quot;closure&quot;,&quot;jsdoc&quot;]</code> if you want to allow
273270
core JSDoc tags, but you want to ensure that Closure Compiler-specific tags are interpreted as Closure Compiler would interpret them.</p>
271+
<h2 id="configuring-templates">Configuring templates</h2>
272+
<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.
273+
See <a href="about-configuring-default-template.html">Configuring JSDoc&#39;s Default
274+
Template</a> for additional options that the default template supports.</p>
275+
<figure><pre class="prettyprint lang-js"><code>{
276+
"templates": {
277+
"cleverLinks": false,
278+
"monospaceLinks": false
279+
}
280+
}
281+
</code></pre>
282+
</figure>
283+
<p>If <code>templates.monospaceLinks</code> is true, all link text from the <a href="tags-inline-link.html">inline <code>{@link}</code>
284+
tag</a> will be rendered in monospace.</p>
285+
<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.
286+
For example, <code>{@link http://github.com}</code> will render in plain text, but <code>{@link MyNamespace.myFunction}</code> will be in monospace.</p>
287+
<p>If <code>templates.cleverLinks</code> is true, <code>templates.monospaceLinks</code> is ignored.</p>
274288
<h2 id="related-links">Related Links</h2>
275289
<ul>
276290
<li>

‎content/en/about-configuring-jsdoc.md

Lines changed: 83 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ If you do not specify a configuration file, JSDoc uses the following configurati
6060
```js
6161
{
6262
"plugins": [],
63+
"recurseDepth": 10,
6364
"source": {
6465
"includePattern": ".+\\.js(doc|x)?$",
6566
"excludePattern": "(^|\\/|\\\\)_"
@@ -79,6 +80,8 @@ If you do not specify a configuration file, JSDoc uses the following configurati
7980
This means:
8081

8182
+ No plugins are loaded (`plugins`).
83+
+ If recursion is enabled with the [`-r` command-line flag][about-commandline], JSDoc will search
84+
for files 10 levels deep (`recurseDepth`).
8285
+ Only files ending in `.js`, `.jsdoc`, and `.jsx` will be processed (`source.includePattern`).
8386
+ Any file starting with an underscore, or in a directory starting with an underscore, will be
8487
ignored (`source.excludePattern`).
@@ -90,10 +93,60 @@ ignored (`source.excludePattern`).
9093

9194
These options and others are explained in the following sections.
9295

96+
[about-commandline]: about-commandline.html
9397
[closure-tags]: https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#jsdoc-tags
9498
[tags-inline-link]: tags-inline-link.html
9599

96100

101+
## Configuring plugins
102+
103+
To enable plugins, add their paths (relative to the JSDoc folder) into the `plugins` array.
104+
105+
For example, the following JSON configuration file will enable the Markdown plugin, which converts
106+
Markdown-formatted text to HTML, and the "summarize" plugin, which autogenerates a summary for each
107+
doclet:
108+
109+
{% example "JSON configuration file with plugins" %}
110+
111+
```
112+
{
113+
"plugins": [
114+
"plugins/markdown",
115+
"plugins/summarize"
116+
]
117+
}
118+
```
119+
{% endexample %}
120+
121+
See the [plugin reference][plugins] for further information, and look in [JSDoc's `plugins`
122+
directory][jsdoc-plugins] for the plugins built into JSDoc.
123+
124+
You can configure the Markdown plugin by adding a `markdown` object to your configuration file. See
125+
[Configuring the Markdown Plugin][markdown] for details.
126+
127+
[jsdoc-plugins]: https://github.com/jsdoc3/jsdoc/tree/master/plugins
128+
[markdown]: plugins-markdown.html
129+
[plugins]: about-plugins.html
130+
131+
132+
## Specifying recursion depth
133+
134+
The `recurseDepth` option controls how many levels deep JSDoc will recursively search for source
135+
files and tutorials. This option is used only if you also specify the [`-r` command-line
136+
flag][about-commandline], which tells JSDoc to recursively search for input files.
137+
138+
{% example %}
139+
140+
```js
141+
{
142+
"recurseDepth": 10
143+
}
144+
```
145+
{% endexample %}
146+
147+
[about-commandline]: about-commandline.html
148+
149+
97150
## Specifying input files
98151

99152
The `source` set of options, in combination with paths given to JSDoc on the command line,
@@ -230,38 +283,48 @@ When options are specified on the command line _and_ in the configuration file,
230283
takes precedence.
231284

232285

233-
## Plugins
234-
235-
To enable plugins, add their paths (relative to the JSDoc folder) into the `plugins` array.
286+
## Configuring tags and tag dictionaries
236287

237-
For example, the following JSON configuration file will enable the Markdown plugin, which converts
238-
Markdown-formatted text to HTML, and the "summarize" plugin, which autogenerates a summary for each
239-
doclet:
288+
The options in `tags` control which JSDoc tags are allowed and how each tag is interpreted.
240289

241-
{% example "JSON configuration file with plugins" %}
290+
{% example %}
242291

243-
```
292+
```js
244293
{
245-
"plugins": [
246-
"plugins/markdown",
247-
"plugins/summarize"
248-
]
294+
"tags": {
295+
"allowUnknownTags": true,
296+
"dictionaries": ["jsdoc","closure"]
297+
}
249298
}
250299
```
251300
{% endexample %}
252301

253-
See the [plugin reference][plugins] for further information, and look in [JSDoc's `plugins`
254-
directory][jsdoc-plugins] for the plugins built into JSDoc.
302+
The `tags.allowUnknownTags` property affects how JSDoc handles unrecognized tags. If you set this
303+
option to `false`, and JSDoc finds a tag that it does not recognize (for example, `@foo`), JSDoc
304+
logs a warning. By default, this option is set to `true`. In JSDoc 3.4.1 and later, you can also
305+
set this property to an array of tag names that JSDoc should allow (for example, `["foo","bar"]`).
255306

256-
You can configure the Markdown plugin by adding a `markdown` object to your configuration file. See
257-
[Configuring the Markdown Plugin][markdown] for details.
307+
The `tags.dictionaries` property controls which tags JSDoc recognizes, as well as how JSDoc
308+
interprets the tags that it recognizes. In JSDoc 3.3.0 and later, there are two built-in tag
309+
dictionaries:
258310

259-
[jsdoc-plugins]: https://github.com/jsdoc3/jsdoc/tree/master/plugins
260-
[markdown]: plugins-markdown.html
261-
[plugins]: about-plugins.html
311+
+ `jsdoc`: Core JSDoc tags.
312+
+ `closure`: [Closure Compiler tags][closure-tags].
262313

314+
By default, both dictionaries are enabled. Also, by default, the `jsdoc` dictionary is listed first;
315+
as a result, if the `jsdoc` dictionary handles a tag differently than the `closure` dictionary, the
316+
`jsdoc` version of the tag takes precedence.
263317

264-
## Template configuration
318+
If you are using JSDoc with a Closure Compiler project, and you want to avoid using tags that
319+
Closure Compiler does not recognize, change the `tags.dictionaries` setting to `["closure"]`. You
320+
can also change this setting to `["closure","jsdoc"]` if you want to allow core JSDoc tags, but you
321+
want to ensure that Closure Compiler-specific tags are interpreted as Closure Compiler would
322+
interpret them.
323+
324+
[closure-tags]: https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#jsdoc-tags
325+
326+
327+
## Configuring templates
265328

266329
The options in `templates` affect the appearance and content of generated documentation. Third-party
267330
templates may not implement all of these options. See [Configuring JSDoc's Default
@@ -290,44 +353,3 @@ If `templates.cleverLinks` is true, `templates.monospaceLinks` is ignored.
290353

291354
[default-template]: about-configuring-default-template.html
292355
[inline-link-tag]: tags-inline-link.html
293-
294-
295-
## Tags and tag dictionaries
296-
297-
The options in `tags` control which JSDoc tags are allowed and how each tag is interpreted.
298-
299-
{% example %}
300-
301-
```js
302-
{
303-
"tags": {
304-
"allowUnknownTags": true,
305-
"dictionaries": ["jsdoc","closure"]
306-
}
307-
}
308-
```
309-
{% endexample %}
310-
311-
The `tags.allowUnknownTags` property affects how JSDoc handles unrecognized tags. If you set this
312-
option to `false`, and JSDoc finds a tag that it does not recognize (for example, `@foo`), JSDoc
313-
logs a warning. By default, this option is set to `true`. In JSDoc 3.4.1 and later, you can also
314-
set this property to an array of tag names that JSDoc should allow (for example, `["foo","bar"]`).
315-
316-
The `tags.dictionaries` property controls which tags JSDoc recognizes, as well as how JSDoc
317-
interprets the tags that it recognizes. In JSDoc 3.3.0 and later, there are two built-in tag
318-
dictionaries:
319-
320-
+ `jsdoc`: Core JSDoc tags.
321-
+ `closure`: [Closure Compiler tags][closure-tags].
322-
323-
By default, both dictionaries are enabled. Also, by default, the `jsdoc` dictionary is listed first;
324-
as a result, if the `jsdoc` dictionary handles a tag differently than the `closure` dictionary, the
325-
`jsdoc` version of the tag takes precedence.
326-
327-
If you are using JSDoc with a Closure Compiler project, and you want to avoid using tags that
328-
Closure Compiler does not recognize, change the `tags.dictionaries` setting to `["closure"]`. You
329-
can also change this setting to `["closure","jsdoc"]` if you want to allow core JSDoc tags, but you
330-
want to ensure that Closure Compiler-specific tags are interpreted as Closure Compiler would
331-
interpret them.
332-
333-
[closure-tags]: https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#jsdoc-tags

0 commit comments

Comments
 (0)
0