-
Notifications
You must be signed in to change notification settings - Fork 105
/
Copy pathabout-block-inline-tags.html
100 lines (97 loc) · 4.49 KB
/
about-block-inline-tags.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
<!DOCTYPE html>
<!-- THIS IS A GENERATED FILE. DO NOT EDIT. -->
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="description" content="Overview of block and inline JSDoc tags.">
<title>Use JSDoc: Block and inline tags</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>
<!--[if lt IE 9]>
<script src="scripts/html5shiv.min.js"></script>
<script src="scripts/html5shiv-printshiv.min.js"></script>
<![endif]-->
</head>
<body>
<header role="banner">
<div class="container">
<h1 class="branding"><a href="./index.html">@use JSDoc</a></h1>
</div>
<!--/.container-->
</header>
<article role="main">
<h1>Block and inline tags</h1>
<h2>Table of Contents</h2>
<ul>
<li>
<a href="#overview">Overview</a>
</li>
<li>
<a href="#examples">Examples</a>
</li>
</ul>
<h2 id="overview">Overview</h2>
<p>JSDoc supports two different kinds of tags:</p>
<ul>
<li><strong>Block tags</strong>, which are at the top level of a JSDoc comment.</li>
<li><strong>Inline tags</strong>, which are within the text of a block tag or a description.</li>
</ul>
<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
documentation, similar to the anchor tag (<code><a></code>) in HTML.</p>
<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
comment.</p>
<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>),
you must escape it with a leading backslash (<code>\</code>). You do not need to use a line break after inline tags.</p>
<p>Most JSDoc tags are block tags. In general, when this site refers to "JSDoc tags," we really mean "block tags."</p>
<h2 id="examples">Examples</h2>
<p>In the following example, <code>@param</code> is a block tag, and <code>{@link}</code> is an inline tag:</p>
<figure>
<figcaption>Block and inline tags in JSDoc comments</figcaption><pre class="prettyprint lang-js"><code>/**
* Set the shoe's color. Use {@link Shoe#setSize} to set the shoe size.
*
* @param {string} color - The shoe's color.
*/
Shoe.prototype.setColor = function(color) {
// ...
};
</code></pre></figure>
<p>You can use inline tags within a description, as shown above, or within a block tag, as shown below:</p>
<figure>
<figcaption>Inline tag used within a block tag</figcaption><pre class="prettyprint lang-js"><code>/**
* Set the shoe's color.
*
* @param {SHOE_COLORS} color - The shoe color. Must be an enumerated
* value of {@link SHOE_COLORS}.
*/
Shoe.prototype.setColor = function(color) {
// ...
};
</code></pre></figure>
<p>When you use multiple block tags in a JSDoc comment, they must be separated by line breaks:</p>
<figure>
<figcaption>Multiple block tags separated by line breaks</figcaption><pre class="prettyprint lang-js"><code>/**
* Set the color and type of the shoelaces.
*
* @param {LACE_COLORS} color - The shoelace color.
* @param {LACE_TYPES} type - The type of shoelace.
*/
Shoe.prototype.setLaceType = function(color, type) {
// ...
};
</code></pre></figure>
</article>
<footer role="contentinfo">
<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-2014 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>