8000 document "nested property" syntax for the `param` tag (#52) · removed-usr/jsdoc.github.io@85e5c65 · GitHub
[go: up one dir, main page]
Skip to content

Commit 85e5c65

Browse files
hegemonichegemonic
committed
document "nested property" syntax for the param tag (jsdoc#52)
1 parent cb76d33 commit 85e5c65

File tree

2 files changed

+107
-15
lines changed

2 files changed

+107
-15
lines changed

‎content/en/tags-param.md

Lines changed: 49 additions & 7 deletions
10000
Original file line numberDiff line numberDiff line change
@@ -13,16 +13,16 @@ related:
1313

1414
## Overview
1515

16-
The @param tag (or @arg or @argument) documents a function parameter.
16+
The `@param` tag provides the name, type, and description of a function parameter.
1717

18-
The @param tag requires you to specify the name of the parameter you are documenting. You can also
18+
The `@param` tag requires you to specify the name of the parameter you are documenting. You can also
1919
include the parameter's type, enclosed in curly brackets, and a description of the parameter.
2020

2121
The parameter type can be a built-in JavaScript type, such as `string` or `Object`, or a
2222
[JSDoc namepath][namepath] to another symbol in your code. If you have written documentation for the
2323
symbol at that namepath, JSDoc will automatically link to the documentation for that symbol. You can
2424
also use a type expression to indicate, for example, that a parameter is not nullable or can accept
25-
any type; see the [@type documentation][tags-type] for details.
25+
any type; see the [`@type` tag documentation][tags-type] for details.
2626

2727
If you provide a description, you can make the JSDoc comment more readable by inserting a hyphen
2828
before the description. Be sure to include a space before and after the hyphen.
@@ -33,7 +33,8 @@ before the description. Be sure to include a space before and after the hyphen.
3333

3434
## Examples
3535

36-
The following examples show how to include names, types, and descriptions in a @param tag.
36+
### Names, types, and descriptions
37+
The following examples show how to include names, types, and descriptions in a `@param` tag.
3738

3839
{% example "Name only" %}
3940

@@ -86,6 +87,45 @@ function sayHello(somebody) {
8687
```
8788
{% endexample %}
8889

90+
### Parameters with properties
91+
If a parameter is expected to have a specific property, you can document that property by providing
92+
an additional `@param` tag. For example, if an `employee` parameter is expected to have `name` and
93+
`department` properties, you can document it as follows:
94+
95+
{% example "Documenting a parameter's properties" %}
96+
97+
```js
98+
/**
99+
* Assign the project to an employee.
100+
* @param {Object} employee - The employee who is responsible for the project.
101+
* @param {string} employee.name - The name of the employee.
102+
* @param {string} employee.department - The employee's department.
103+
*/
104+
Project.prototype.assign = function(employee) {
105+
// ...
106+
};
107+
```
108+
{% endexample %}
109+
110+
You can also combine this syntax with JSDoc's syntax for array parameters. For example, if multiple
111+
employees can be assigned to a project:
112+
113+
{% example "Documenting properties of values in an array" %}
114+
115+
```js
116+
/**
117+
* Assign the project to a list of employees.
118+
* @param {Object[]} employees - The employees who are responsible for the project.
119+
* @param {string} employees[].name - The name of an employee.
120+
* @param {string} employees[].department - The employee's department.
121+
*/
122+
Project.prototype.assign = function(employees) {
123+
// ...
124+
};
125+
```
126+
{% endexample %}
127+
128+
### Optional parameters and default values
89129
The following examples show how to indicate that a parameter is optional and has a default value.
90130

91131
{% example "An optional parameter (using JSDoc syntax)" %}
@@ -133,9 +173,10 @@ function sayHello(somebody) {
133173
```
134174
{% endexample %}
135175

176+
### Multiple types and repeatable parameters
136177
The following examples show how to use type expressions to indicate that a parameter can accept
137178
multiple types (or any type), and that a parameter can be provided more than once. See the
138-
[@type documentation][type-tag] for details about the type expressions that JSDoc supports.
179+
[`@type` tag documentation][type-tag] for details about the type expressions that JSDoc supports.
139180

140181
{% example "Allows one type OR another type (type union)" %}
141182

@@ -183,8 +224,9 @@ function sum(num) {
183224
```
184225
{% endexample %}
185226

186-
If a parameter accepts a callback function, you can use the [@callback tag][callback-tag] to define
187-
a callback type, then include the callback type in the @param tag.
227+
### Callback functions
228+
If a parameter accepts a callback function, you can use the [`@callback` tag][callback-tag] to
229+
define a callback type, then include the callback type in the `@param` tag.
188230

189231
{% example "Parameters that accept a callback" %}
190232

‎tags-param.html

Lines changed: 58 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,23 @@ <h2>Table of Contents</h2>
3232
</li>
3333
<li>
3434
<a href="#examples">Examples</a>
35+
<ul>
36+
<li>
37+
<a href="#names-types-and-descriptions">Names, types, and descriptions</a>
38+
</li>
39+
<li>
40+
<a href="#parameters-with-properties">Parameters with properties</a>
41+
</li>
42+
<li>
43+
<a href="#optional-parameters-and-default-values">Optional parameters and default values</a>
44+
</li>
45+
<li>
46+
<a href="#multiple-types-and-repeatable-parameters">Multiple types and repeatable parameters</a>
47+
</li>
48+
<li>
49+
<a href="#callback-functions">Callback functions</a>
50+
</li>
51+
</ul>
3552
</li>
3653
<li>
3754
<a href="#related-links">Related Links</a>
@@ -47,17 +64,18 @@ <h2 id="synonyms">Synonyms</h2>
4764
</li>
4865
</ul>
4966
<h2 id="overview">Overview</h2>
50-
<p>The @param tag (or @arg or @argument) documents a function parameter.</p>
51-
<p>The @param tag requires you to specify the name of the parameter you are documenting. You can also include the parameter&#39;s type, enclosed in curly brackets,
52-
and a description of the parameter.</p>
67+
<p>The <code>@param</code> tag provides the name, type, and description of a function parameter.</p>
68+
<p>The <code>@param</code> tag requires you to specify the name of the parameter you are documenting. You can also include the parameter&#39;s type, enclosed in
69+
curly brackets, and a description of the parameter.</p>
5370
<p>The parameter type can be a built-in JavaScript type, such as <code>string</code> or <code>Object</code>, or a
5471
<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
5572
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
56-
or can accept any type; see the [@type documentation][tags-type] for details.</p>
73+
or can accept any type; see the [<code>@type</code> tag documentation][tags-type] for details.</p>
5774
<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
5875
after the hyphen.</p>
5976
<h2 id="examples">Examples</h2>
60-
<p>The following examples show how to include names, types, and descriptions in a @param tag.</p>
77+
<h3 id="names-types-and-descriptions">Names, types, and descriptions</h3>
78+
<p>The following examples show how to include names, types, and descriptions in a <code>@param</code> tag.</p>
6179
<figure>
6280
<figcaption>Name only</figcaption><pre class="prettyprint lang-js"><code>/**
6381
* @param somebody
@@ -95,6 +113,36 @@ <h2 id="examples">Examples</h2>
95113
}
96114
</code></pre>
97115
</figure>
116+
<h3 id="parameters-with-properties">Parameters with properties</h3>
117+
<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
118+
<code>employee</code> parameter is expected to have <code>name</code> and
119+
<code>department</code> properties, you can document it as follows:</p>
120+
<figure>
121+
<figcaption>Documenting a parameter&#39;s properties</figcaption><pre class="prettyprint lang-js"><code>/**
122+
* Assign the project to an employee.
123+
* @param {Object} employee - The employee who is responsible for the project.
124+
* @param {string} employee.name - The name of the employee.
125+
* @param {string} employee.department - The employee's department.
126+
*/
127+
Project.prototype.assign = function(employee) {
128+
// ...
129+
};
130+
</code></pre>
131+
</figure>
132+
<p>You can also combine this syntax with JSDoc&#39;s syntax for array parameters. For example, if multiple employees can be assigned to a project:</p>
133+
<figure>
134+
<figcaption>Documenting properties of values in an array</figcaption><pre class="prettyprint lang-js"><code>/**
135+
* Assign the project to a list of employees.
136+
* @param {Object[]} employees - The employees who are responsible for the project.
137+
* @param {string} employees[].name - The name of an employee.
138+
* @param {string} employees[].department - The employee's department.
139+
*/
140+
Project.prototype.assign = function(employees) {
141+
// ...
142+
};
143+
</code></pre>
144+
</figure>
145+
<h3 id="optional-parameters-and-default-values">Optional parameters and default values</h3>
98146
<p>The following examples show how to indicate that a parameter is optional and has a defa DDB3 ult value.</p>
99147
<figure>
100148
<figcaption>An optional parameter (using JSDoc syntax)</figcaption><pre class="prettyprint lang-js"><code>/**
@@ -132,9 +180,10 @@ <h2 id="examples">Examples</h2>
132180
}
133181
</code></pre>
134182
</figure>
183+
<h3 id="multiple-types-and-repeatable-parameters">Multiple types and repeatable parameters</h3>
135184
<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
136185
more than once. See the
137-
<a href="tags-type.html">@type documentation</a> for details about the type expressions that JSDoc supports.</p>
186+
<a href="tags-type.html"><code>@type</code> tag documentation</a> for details about the type expressions that JSDoc supports.</p>
138187
<figure>
139188
<figcaption>Allows one type OR another type (type union)</figcaption><pre class="prettyprint lang-js"><code>/**
140189
* @param {(string|string[])} [somebody=John Doe] - Somebody's name, or an array of names.
@@ -172,8 +221,9 @@ <h2 id="examples">Examples</h2>
172221
}
173222
</code></pre>
174223
</figure>
175-
<p>If a parameter accepts a callback function, you can use the <a href="tags-callback.html">@callback tag</a> to define a callback type, then include the callback
176-
type in the @param tag.</p>
224+
<h3 id="callback-functions">Callback functions</h3>
225+
<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
226+
the callback type in the <code>@param</code> tag.</p>
177227
<figure>
178228
<figcaption>Parameters that accept a callback</figcaption><pre class="prettyprint lang-js"><code>/**
179229
* This callback type is called `requestCallback` and is displayed as a global symbol.

0 commit comments

Comments
 (0)
0