You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<p>JSDoc supports two different kinds of tags:</p>
36
+
<ul>
37
+
<li><strong>Block tags</strong>, which are at the top level of a JSDoc comment.</li>
38
+
<li><strong>Inline tags</strong>, which are within the text of a block tag or a description.</li>
39
+
</ul>
40
+
<p>Block tags usually provide detailed information about your code, such as the parameters that a function accepts. Inline tags usually link to other parts of the
41
+
documentation, similar to the anchor tag (<code><a></code>) in HTML.</p>
42
+
<p>Block tags always begin with an at sign (<code>@</code>). Each block tag must be followed by a line break, with the exception of the last block tag in a JSDoc
43
+
comment.</p>
44
+
<p>Inline tags also begin with an at sign. However, inline tags and their text must be enclosed in curly braces (<code>{</code> and <code>}</code>). The <code>{</code> denotes the start of the inline tag, and the <code>}</code> denotes the end of the inline tag. If your tag's text includes a closing curly brace (<code>}</code>),
45
+
you must escape it with a leading backslash (<code>\</code>). You do not need to use a line break after inline tags.</p>
46
+
<p>Most JSDoc tags are block tags. In general, when this site refers to "JSDoc tags," we really mean "block tags."</p>
47
+
<h2id="examples">Examples</h2>
48
+
<p>In the following example, <code>@param</code> is a block tag, and <code>{@link}</code> is an inline tag:</p>
49
+
<figure>
50
+
<figcaption>Block and inline tags in JSDoc comments</figcaption><preclass="prettyprint lang-js"><code>/**
51
+
* Set the shoe's color. Use {@link Shoe#setSize} to set the shoe size.
52
+
*
53
+
* @param {string} color - The shoe's color.
54
+
*/
55
+
Shoe.prototype.setColor = function(color) {
56
+
// ...
57
+
};
58
+
</code></pre>
59
+
</figure>
60
+
<p>You can use inline tags within a description, as shown above, or within a block tag, as shown below:</p>
61
+
<figure>
62
+
<figcaption>Inline tag used within a block tag</figcaption><preclass="prettyprint lang-js"><code>/**
63
+
* Set the shoe's color.
64
+
*
65
+
* @param {SHOE_COLORS} color - The shoe color. Must be an enumerated
66
+
* value of {@link SHOE_COLORS}.
67
+
*/
68
+
Shoe.prototype.setColor = function(color) {
69
+
// ...
70
+
};
71
+
</code></pre>
72
+
</figure>
73
+
<p>When you use multiple block tags in a JSDoc comment, they must be separated by line breaks:</p>
74
+
<figure>
75
+
<figcaption>Multiple block tags separated by line breaks</figcaption><preclass="prettyprint lang-js"><code>/**
76
+
* Set the color and type of the shoelaces.
77
+
*
78
+
* @param {LACE_COLORS} color - The shoelace color.
79
+
* @param {LACE_TYPES} type - The type of shoelace.
<ahref="https://github.com/jsdoc3/jsdoc3.github.com/contributors">contributors</a> to the JSDoc 3 documentation project.
93
+
<br> This website is <ahref="https://github.com/jsdoc3/jsdoc3.github.com">open source</a> and is licensed under the <arel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
<li><code>@link</code> tags are rendered in plain text (<code>templates.cleverLinks</code>, <code>templates.monospaceLinks</code>).</li>
82
78
</ul>
83
-
<p>These options and others will be further explained on this page. A full example is provided at the end.
84
-
</p>
79
+
<p>These options and others will be further explained on this page.</p>
85
80
<p>Further settings may be added to the file as requested by various plugins or templates (for example, the <ahref="plugins-markdown.html">Markdown plugin</a> can be configured by including a "markdown" key).</p>
<p>The "source" set of options, in combination with paths given to JSDoc on the command-line, determine what files JSDoc generates documentation for.
<p>It is possible to put many of JSDoc's <ahref="about-commandline.html">command-line options</a> into the configuration file instead of specifying them on
169
164
the command-line. To do this, use the longnames of the relevant options in an "opts" section of conf.json with the value being the option's value.</p>
170
165
<figure>
171
-
<figcaption>Example</figcaption><preclass="prettyprint lang-js"><code>// You must remove the comments before adding these options to your .json file
172
-
"opts": {
166
+
<figcaption>Command-line options set in the configuration file</figcaption><preclass="prettyprint lang-js"><code>"opts": {
173
167
"template": "templates/default", // same as -t templates/default
174
168
"encoding": "utf8", // same as -e utf8
175
169
"destination": "./out/", // same as -d ./out/
176
170
"recurse": true, // same as -r
177
171
"tutorials": "path/to/tutorials", // same as -u path/to/tutorials
178
-
"query": "value", // same as -q value
179
-
"private": true, // same as -p
180
-
"lenient": true, // same as -l
181
-
// these can also be included, though you probably wouldn't bother
182
-
// putting these in conf.json rather than the command line as they cause
183
-
// JSDoc not to produce documentation.
184
-
"version": true, // same as --version or -v
185
-
"explain": true, // same as -X
186
-
"test": true, // same as -T
187
-
"help": true, // same as --help or -h
188
-
"verbose": true, // same as --verbose, only relevant to tests.
189
-
"match": "value", // same as --match value, only relevant to tests.
190
-
"nocolor": true // same as --nocolor, only relevant to tests
<p>To enable plugins, add their paths (relative to the JSDoc folder) into the <code>plugins</code> array.</p>
202
-
<p>For example, the following will include the Markdown plugin and verbose output plugin:</p>
183
+
<p>For example, the following will include the Markdown plugin, which converts Markdown-formatted text to HTML, and the "summarize" plugin, which autogenerates
<p>If <code>templates.monospaceLinks</code> is true, all link texts from the <ahref="tags-link.html">@link</a> tag will be rendered in monospace.</p>
203
+
<p>If <code>templates.monospaceLinks</code> is true, all link texts from the <ahref="tags-inline-link.html">@link</a> tag will be rendered in monospace.</p>
222
204
<p>If <code>templates.cleverLinks</code> is true, {@link asdf} will be rendered in normal font if "asdf" is a URL, and monospace otherwise. For example,
223
205
<code>{@link http://github.com}</code> will render in plain-text but
224
206
<code>{@link MyNamespace.myFunction}</code> will be in monospace.</p>
225
207
<p>If <code>templates.cleverLinks</code> is true, it is used and <code>templates.monospaceLinks</code> is ignored.</p>
226
-
<p>Also, there are {@linkcode ...} and {@linkplain ...} if one wishes to force the link to be rendered in monospace or normal font respectively (see <ahref="tags-link.html">@link, @linkcode and @linkplain</a> for further information).</p>
208
+
<p>Also, there are {@linkcode ...} and {@linkplain ...} if one wishes to force the link to be rendered in monospace or normal font respectively (see <ahref="tags-inline-link.html">@link, @linkcode and @linkplain</a> for further information).</p>
227
209
<h3id="miscellaneous">Miscellaneous</h3>
228
210
<p>The <code>tags.allowUnknownTags</code> property determines whether tags unrecognised by JSDoc are permitted. If this is false and JSDoc encounters a tag it does
229
211
not recognise (e.g. <code>@foobar</code>), it will throw an error. Otherwise, it will just ignore the tag.</p>
230
212
<p>By default, it is true.</p>
231
213
<figure><preclass="prettyprint"><code>"tags": {
232
214
"allowUnknownTags": true
233
215
}
234
-
</code></pre>
235
-
</figure>
236
-
<h2id="example-with-all-configuration-options">Example with all configuration options</h2>
237
-
<p>Here is an example conf.json showing all possible configuration options native to the base JSDoc, along with their default values.</p>
238
-
<figure>
239
-
<figcaption>A conf.json showcasing all the configuration options to base JSDoc</figcaption><preclass="prettyprint lang-js"><code>// You must remove the comments before adding these options to your .json file
240
-
{
241
-
"tags": {
242
-
"allowUnknownTags": true
243
-
},
244
-
"source": {
245
-
"include": [],
246
-
"exclude": [],
247
-
"includePattern": ".+\\.js(doc)?$",
248
-
"excludePattern": "(^|\\/|\\\\)_"
249
-
},
250
-
"plugins": [],
251
-
"templates": {
252
-
"cleverLinks": false,
253
-
"monospaceLinks": false
254
-
},
255
-
"opts": {
256
-
"template": "templates/default", // same as -t templates/default
257
-
"encoding": "utf8", // same as -e utf8
258
-
"destination": "./out/", // same as -d ./out/
259
-
"recurse": true, // same as -r
260
-
"tutorials": "path/to/tutorials", // same as -u path/to/tutorials, default "" (no tutorials)
261
-
"query": "value", // same as -q value, default "" (no query)
262
-
"private": true, // same as -p
263
-
"lenient": true, // same as -l
264
-
// these can also be included, though you probably wouldn't bother
265
-
// putting these in conf.json rather than the command line as they cause
266
-
// JSDoc not to produce documentation.
267
-
"version": true, // same as --version or -v
268
-
"explain": true, // same as -X
269
-
"test": true, // same as -T
270
-
"help": true, // same as --help or -h
271
-
"verbose": true, // same as --verbose, only relevant to tests.
272
-
"match": "value", // same as --match value, only relevant to tests.
273
-
"nocolor": true // same as --nocolor, only relevant to tests
0 commit comments