Skip to content

Commit 2dc6301

Browse files
committed
separate block tags from inline tags (#79)
1 parent cd9b01d commit 2dc6301

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+720
-1154
lines changed

about-block-inline-tags.html

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
<!DOCTYPE html>
2+
<!-- THIS IS A GENERATED FILE. DO NOT EDIT. -->
3+
<html lang="en">
4+
5+
<head>
6+
<meta charset="utf-8">
7+
<meta name="description" content="Overview of block and inline JSDoc tags.">
8+
<title>Use JSDoc: Block and inline tags</title>
9+
<link rel="stylesheet" href="styles/usejsdoc.css">
10+
<link rel="stylesheet" href="styles/prettify.css">
11+
<link rel="stylesheet" href="styles/css3-github-ribbon.css">
12+
<script src="scripts/prettify.js"></script>
13+
<!--[if lt IE 9]>
14+
<script src="scripts/html5shiv.min.js"></script>
15+
<script src="scripts/html5shiv-printshiv.min.js"></script>
16+
<![endif]-->
17+
</head>
18+
19+
<body>
20+
<header>
21+
<a href="./index.html">@use JSDoc</a>
22+
</header>
23+
<article>
24+
<h1>Block and inline tags</h1>
25+
<h2>Table of Contents</h2>
26+
<ul>
27+
<li>
28+
<a href="#overview">Overview</a>
29+
</li>
30+
<li>
31+
<a href="#examples">Examples</a>
32+
</li>
33+
</ul>
34+
<h2 id="overview">Overview</h2>
35+
<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>&lt;a&gt;</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&#39;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 &quot;JSDoc tags,&quot; we really mean &quot;block tags.&quot;</p>
47+
<h2 id="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><pre class="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><pre class="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><pre class="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.
80+
*/
81+
Shoe.prototype.setLaceType = function(color, type) {
82+
// ...
83+
};
84+
</code></pre>
85+
</figure>
86+
</article>
87+
<footer>
88+
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">
89+
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" />
90+
</a>
91+
<br> Copyright &#169; 2011-2014 the
92+
<a href="https://github.com/jsdoc3/jsdoc3.github.com/contributors">contributors</a> to the JSDoc 3 documentation project.
93+
<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/">
94+
Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
95+
</footer>
96+
<script type="text/javascript">
97+
prettyPrint();
98+
</script>
99+
</body>
100+
101+
</html>

about-configuring-jsdoc.html

Lines changed: 8 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -44,9 +44,6 @@ <h2>Table of Contents</h2>
4444
</li>
4545
</ul>
4646
</li>
47-
<li>
48-
<a href="#example-with-all-configuration-options">Example with all configuration options</a>
49-
</li>
5047
<li>
5148
<a href="#related-links">Related Links</a>
5249
</li>
@@ -77,11 +74,9 @@ <h2 id="configuration-file">Configuration File</h2>
7774
<li>Any file starting with an underscore or in a directory starting with an underscore will be
7875
<em>ignored</em> (<code>source.excludePattern</code>);</li>
7976
<li>No plugins are loaded (<code>plugins</code>);</li>
80-
<li>@link tags are rendered as-is (i.e. in plain text as opposed to monospace) (
81-
<code>templates.cleverLinks</code>, <code>templates.monospaceLinks</code>).</li>
77+
<li><code>@link</code> tags are rendered in plain text (<code>templates.cleverLinks</code>, <code>templates.monospaceLinks</code>).</li>
8278
</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>
8580
<p>Further settings may be added to the file as requested by various plugins or templates (for example, the <a href="plugins-markdown.html">Markdown plugin</a> can be configured by including a &quot;markdown&quot; key).</p>
8681
<h2 id="specifying-input-files">Specifying input files</h2>
8782
<p>The &quot;source&quot; set of options, in combination with paths given to JSDoc on the command-line, determine what files JSDoc generates documentation for.
@@ -168,26 +163,12 @@ <h2 id="incorporating-command-line-options-into-the-configuration-file">Incorpor
168163
<p>It is possible to put many of JSDoc&#39;s <a href="about-commandline.html">command-line options</a> into the configuration file instead of specifying them on
169164
the command-line. To do this, use the longnames of the relevant options in an &quot;opts&quot; section of conf.json with the value being the option&#39;s value.</p>
170165
<figure>
171-
<figcaption>Example</figcaption><pre class="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><pre class="prettyprint lang-js"><code>"opts": {
173167
"template": "templates/default", // same as -t templates/default
174168
"encoding": "utf8", // same as -e utf8
175169
"destination": "./out/", // same as -d ./out/
176170
"recurse": true, // same as -r
177171
"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
191172
}
192173
</code></pre>
193174
</figure>
@@ -199,10 +180,11 @@ <h2 id="incorporating-command-line-options-into-the-configuration-file">Incorpor
199180
</p>
200181
<h2 id="plugins">Plugins</h2>
201182
<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 &quot;summarize&quot; plugin, which autogenerates
184+
a summary for each doclet:</p>
203185
<figure><pre class="prettyprint"><code>"plugins": [
204186
"plugins/markdown",
205-
"plugins/verboseOutput"
187+
"plugins/summarize"
206188
]
207189
</code></pre>
208190
</figure>
@@ -218,60 +200,19 @@ <h2 id="output-style-configuration">Output style configuration</h2>
218200
}
219201
</code></pre>
220202
</figure>
221-
<p>If <code>templates.monospaceLinks</code> is true, all link texts from the <a href="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 <a href="tags-inline-link.html">@link</a> tag will be rendered in monospace.</p>
222204
<p>If <code>templates.cleverLinks</code> is true, {@link asdf} will be rendered in normal font if &quot;asdf&quot; is a URL, and monospace otherwise. For example,
223205
<code>{@link http://github.com}</code> will render in plain-text but
224206
<code>{@link MyNamespace.myFunction}</code> will be in monospace.</p>
225207
<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 <a href="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 <a href="tags-inline-link.html">@link, @linkcode and @linkplain</a> for further information).</p>
227209
<h3 id="miscellaneous">Miscellaneous</h3>
228210
<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
229211
not recognise (e.g. <code>@foobar</code>), it will throw an error. Otherwise, it will just ignore the tag.</p>
230212
<p>By default, it is true.</p>
231213
<figure><pre class="prettyprint"><code>"tags": {
232214
"allowUnknownTags": true
233215
}
234-
</code></pre>
235-
</figure>
236-
<h2 id="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><pre class="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
274-
}
275216
</code></pre>
276217
</figure>
277218
<h2 id="related-links">Related Links</h2>

0 commit comments

Comments
 (0)