forked from jsdoc/jsdoc.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathtags-param.html
More file actions
275 lines (271 loc) · 10.3 KB
/
tags-param.html
File metadata and controls
275 lines (271 loc) · 10.3 KB
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
<!DOCTYPE html>
<!-- THIS IS A GENERATED FILE. DO NOT EDIT. -->
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="description" content="Document the parameter to a function.">
<title>Use JSDoc: @param</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>
<a href="./index.html">@use JSDoc</a>
</header>
<article>
<h1>@param</h1>
<h2>Table of Contents</h2>
<ul>
<li>
<a href="#synonyms">Synonyms</a>
</li>
<li>
<a href="#overview">Overview</a>
</li>
<li>
<a href="#examples">Examples</a>
<ul>
<li>
<a href="#names-types-and-descriptions">Names, types, and descriptions</a>
</li>
<li>
<a href="#parameters-with-properties">Parameters with properties</a>
</li>
<li>
<a href="#optional-parameters-and-default-values">Optional parameters and default values</a>
</li>
<li>
<a href="#multiple-types-and-repeatable-parameters">Multiple types and repeatable parameters</a>
</li>
<li>
<a href="#callback-functions">Callback functions</a>
</li>
</ul>
</li>
<li>
<a href="#related-links">Related Links</a>
</li>
</ul>
<h2 id="synonyms">Synonyms</h2>
<ul>
<li>
<code>@arg</code>
</li>
<li>
<code>@argument</code>
</li>
</ul>
<h2 id="overview">Overview</h2>
<p>The <code>@param</code> tag provides the name, type, and description of a function parameter.</p>
<p>The <code>@param</code> tag requires you to specify the name of the parameter you are documenting. You can also include the parameter's type, enclosed in
curly brackets, and a description of the parameter.</p>
<p>The parameter type can be a built-in JavaScript type, such as <code>string</code> or <code>Object</code>, or a
<a href="about-namepaths.html">JSDoc namepath</a> to another symbol in your code. If you have written documentation for the symbol at that namepath, JSDoc
will automatically link to the documentation for that symbol. You can also use a type expression to indicate, for example, that a parameter is not nullable
or can accept any type; see the <a href="tags-type.html"><code>@type</code> tag documentation</a> for details.</p>
<p>If you provide a description, you can make the JSDoc comment more readable by inserting a hyphen before the description. Be sure to include a space before and
after the hyphen.</p>
<h2 id="examples">Examples</h2>
<h3 id="names-types-and-descriptions">Names, types, and descriptions</h3>
<p>The following examples show how to include names, types, and descriptions in a <code>@param</code> tag.</p>
<figure>
<figcaption>Name only</figcaption><pre class="prettyprint lang-js"><code>/**
* @param somebody
*/
function sayHello(somebody) {
alert('Hello ' + somebody);
}
</code></pre>
</figure>
<figure>
<figcaption>Name and type</figcaption><pre class="prettyprint lang-js"><code>/**
* @param {string} somebody
*/
function sayHello(somebody) {
alert('Hello ' + somebody);
}
</code></pre>
</figure>
<figure>
<figcaption>Name, type, and description</figcaption><pre class="prettyprint lang-js"><code>/**
* @param {string} somebody Somebody's name.
*/
function sayHello(somebody) {
alert('Hello ' + somebody);
}
</code></pre>
</figure>
<p>You can add a hyphen before the description to make it more readable. Be sure to include a space before and after the hyphen.</p>
<figure>
<figcaption>Name, type, and description, with a hyphen before the description</figcaption><pre class="prettyprint lang-js"><code>/**
* @param {string} somebody - Somebody's name.
*/
function sayHello(somebody) {
alert('Hello ' + somebody);
}
</code></pre>
</figure>
<h3 id="parameters-with-properties">Parameters with properties</h3>
<p>If a parameter is expected to have a specific property, you can document that property by providing an additional <code>@param</code> tag. For example, if an
<code>employee</code> parameter is expected to have <code>name</code> and
<code>department</code> properties, you can document it as follows:</p>
<figure>
<figcaption>Documenting a parameter's properties</figcaption><pre class="prettyprint lang-js"><code>/**
* Assign the project to an employee.
* @param {Object} employee - The employee who is responsible for the project.
* @param {string} employee.name - The name of the employee.
* @param {string} employee.department - The employee's department.
*/
Project.prototype.assign = function(employee) {
// ...
};
</code></pre>
</figure>
<p>You can also combine this syntax with JSDoc's syntax for array parameters. For example, if multiple employees can be assigned to a project:</p>
<figure>
<figcaption>Documenting properties of values in an array</figcaption><pre class="prettyprint lang-js"><code>/**
* Assign the project to a list of employees.
* @param {Object[]} employees - The employees who are responsible for the project.
* @param {string} employees[].name - The name of an employee.
* @param {string} employees[].department - The employee's department.
*/
Project.prototype.assign = function(employees) {
// ...
};
</code></pre>
</figure>
<h3 id="optional-parameters-and-default-values">Optional parameters and default values</h3>
<p>The following examples show how to indicate that a parameter is optional and has a default value.</p>
<figure>
<figcaption>An optional parameter (using JSDoc syntax)</figcaption><pre class="prettyprint lang-js"><code>/**
* @param {string} [somebody] - Somebody's name.
*/
function sayHello(somebody) {
if (!somebody) {
somebody = 'John Doe';
}
alert('Hello ' + somebody);
}
</code></pre>
</figure>
<figure>
<figcaption>An optional parameter (using Google Closure Compiler syntax)</figcaption><pre class="prettyprint lang-js"><code>/**
* @param {string=} somebody - Somebody's name.
*/
function sayHello(somebody) {
if (!somebody) {
somebody = 'John Doe';
}
alert('Hello ' + somebody);
}
</code></pre>
</figure>
<figure>
<figcaption>An optional parameter and default value</figcaption><pre class="prettyprint lang-js"><code>/**
* @param {string} [somebody=John Doe] - Somebody's name.
*/
function sayHello(somebody) {
if (!somebody) {
somebody = 'John Doe';
}
alert('Hello ' + somebody);
}
</code></pre>
</figure>
<h3 id="multiple-types-and-repeatable-parameters">Multiple types and repeatable parameters</h3>
<p>The following examples show how to use type expressions to indicate that a parameter can accept multiple types (or any type), and that a parameter can be provided
more than once. See the
<a href="tags-type.html"><code>@type</code> tag documentation</a> for details about the type expressions that JSDoc supports.</p>
<figure>
<figcaption>Allows one type OR another type (type union)</figcaption><pre class="prettyprint lang-js"><code>/**
* @param {(string|string[])} [somebody=John Doe] - Somebody's name, or an array of names.
*/
function sayHello(somebody) {
if (!somebody) {
somebody = 'John Doe';
} else if (Array.isArray(somebody)) {
somebody = somebody.join(', ');
}
alert('Hello ' + somebody);
}
</code></pre>
</figure>
<figure>
<figcaption>Allows any type</figcaption><pre class="prettyprint lang-js"><code>/**
* @param {*} somebody - Whatever you want.
*/
function sayHello(somebody) {
console.log('Hello ' + JSON.stringify(somebody));
}
</code></pre>
</figure>
<figure>
<figcaption>Allows a parameter to be repeated</figcaption><pre class="prettyprint lang-js"><code>/**
* Returns the sum of all numbers passed to the function.
* @param {...number} num - A positive or negative number.
*/
function sum(num) {
var i = 0, n = arguments.length, t = 0;
for (; i < n; i++) {
t += arguments[i];
}
return t;
}
</code></pre>
</figure>
<h3 id="callback-functions">Callback functions</h3>
<p>If a parameter accepts a callback function, you can use the <a href="tags-callback.html"><code>@callback</code> tag</a> to define a callback type, then include
the callback type in the <code>@param</code> tag.</p>
<figure>
<figcaption>Parameters that accept a callback</figcaption><pre class="prettyprint lang-js"><code>/**
* This callback type is called `requestCallback` and is displayed as a global symbol.
*
* @callback requestCallback
* @param {number} responseCode
* @param {string} responseMessage
*/
/**
* Does something asynchronously and executes the callback on completion.
* @param {requestCallback} cb - The callback that handles the response.
*/
function doSomethingAsynchronously(cb) {
// code
};
</code></pre>
</figure>
<h2 id="related-links">Related Links</h2>
<ul>
<li>
<a href="tags-callback.html">@callback</a>
</li>
<li>
<a href="tags-returns.html">@returns</a>
</li>
<li>
<a href="tags-type.html">@type</a>
</li>
<li>
<a href="tags-typedef.html">@typedef</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>