Skip to content

Commit 805c71c

Browse files
hegemonichegemonic
committed
document yields tag (#169)
1 parent b171945 commit 805c71c

File tree

5 files changed

+181
-13
lines changed

5 files changed

+181
-13
lines changed

‎content/en/tags-returns.md‎

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,27 @@ synonyms:
55
- return
66
related:
77
- tags-param.html
8+
- tags-yields.html
89
---
910

11+
## Syntax
12+
13+
`@returns [{type}] [description]`
14+
15+
1016
## Overview
1117

12-
The @returns tag documents the value that a function returns.
18+
The `@returns` tag documents the value that a function returns.
19+
20+
If you are documenting a generator function, use the [`@yields` tag][yields-tag] instead of this
21+
tag.
22+
23+
[yields-tag]: tags-yields.html
1324

1425

1526
## Examples
1627

17-
{% example "Type of the return value" %}
28+
{% example "Return value with a type" %}
1829

1930
```js
2031
/**
@@ -29,7 +40,7 @@ function sum(a, b) {
2940
```
3041
{% endexample %}
3142

32-
{% example "Type and description of the return value" %}
43+
{% example "Return value with a type and description" %}
3344

3445
```js
3546
/**
@@ -44,15 +55,15 @@ function sum(a, b) {
4455
```
4556
{% endexample %}
4657

47-
{% example "The return value can have different types" %}
58+
{% example "Return value with multiple types" %}
4859

4960
```js
5061
/**
5162
* Returns the sum of a and b
5263
* @param {Number} a
5364
* @param {Number} b
5465
* @param {Boolean} retArr If set to true, the function will return an array
55-
* @returns {Number|Array} Sum of a and b or an array that contains a, b and the sum of a and b.
66+
* @returns {(Number|Array)} Sum of a and b or an array that contains a, b and the sum of a and b.
5667
*/
5768
function sum(a, b, retArr) {
5869
if (retArr) {

‎content/en/tags-yields.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
tag: yields
3+
description: Document the value yielded by a generator function.
4+
synonyms:
5+
- yield
6+
related:
7+
- tags-returns.html
8+
---
9+
10+
## Syntax
11+
12+
`@yields [{type}] [description]`
13+
14+
15+
## Overview
16+
17+
The `@yields` tag documents the value that is yielded by a generator function. This tag is available
18+
in JSDoc 3.5.0 and later.
19+
20+
If you are documenting a regular function, use the [`@returns` tag][returns-tag] instead of this
21+
tag.
22+
23+
[returns-tag]: tags-returns.html
24+
25+
26+
## Examples
27+
28+
{% example "@yields tag with a type" %}
29+
30+
```js
31+
/**
32+
* Generate the Fibonacci sequence of numbers.
33+
*
34+
* @yields {number}
35+
*/
36+
function* fibonacci() {}
37+
```
38+
{% endexample %}
39+
40+
{% example "@yields tag with a type and description" %}
41+
42+
```js
43+
/**
44+
* Generate the Fibonacci sequence of numbers.
45+
*
46+
* @yields {number} The next number in the Fibonacci sequence.
47+
*/
48+
function* fibonacci() {}
49+
```
50+
{% endexample %}

‎index.html‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -190,6 +190,8 @@ <h2 id="block-tags">Block Tags</h2>
190190
<dd>Distinguish different objects with the same name.</dd>
191191
<dt><a href="tags-version.html">@version</a></dt>
192192
<dd>Documents the version number of an item.</dd>
193+
<dt><a href="tags-yields.html">@yields</a> (synonyms: @yield)</dt>
194+
<dd>Document the value yielded by a generator function.</dd>
193195
</dl>
194196
<h2 id="inline-tags">Inline Tags</h2>
195197
<dl>

‎tags-returns.html‎

Lines changed: 21 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,9 @@ <h2>Table of Contents</h2>
2727
<li>
2828
<a href="#synonyms">Synonyms</a>
2929
</li>
30+
<li>
31+
<a href="#syntax">Syntax</a>
32+
</li>
3033
<li>
3134
<a href="#overview">Overview</a>
3235
</li>
@@ -41,11 +44,16 @@ <h2 id="synonyms">Synonyms</h2>
4144
<p>
4245
<code>@return</code>
4346
</p>
47+
<h2 id="syntax">Syntax</h2>
48+
<p><code>@returns [{type}] [description]</code>
49+
</p>
4450
<h2 id="overview">Overview</h2>
45-
<p>The @returns tag documents the value that a function returns.</p>
51+
<p>The <code>@returns</code> tag documents the value that a function returns.</p>
52+
<p>If you are documenting a generator function, use the <a href="tags-yields.html"><code>@yields</code> tag</a> instead of this tag.
53+
</p>
4654
<h2 id="examples">Examples</h2>
4755
<figure>
48-
<figcaption>Type of the return value</figcaption><pre class="prettyprint lang-js"><code>/**
56+
<figcaption>Return value with a type</figcaption><pre class="prettyprint lang-js"><code>/**
4957
* Returns the sum of a and b
5058
* @param {Number} a
5159
* @param {Number} b
@@ -57,7 +65,7 @@ <h2 id="examples">Examples</h2>
5765
</code></pre>
5866
</figure>
5967
<figure>
60-
<figcaption>Type and description of the return value</figcaption><pre class="prettyprint lang-js"><code>/**
68+
<figcaption>Return value with a type and description</figcaption><pre class="prettyprint lang-js"><code>/**
6169
* Returns the sum of a and b
6270
* @param {Number} a
6371
* @param {Number} b
@@ -69,12 +77,12 @@ <h2 id="examples">Examples</h2>
6977
</code></pre>
7078
</figure>
7179
<figure>
72-
<figcaption>The return value can have different types</figcaption><pre class="prettyprint lang-js"><code>/**
80+
<figcaption>Return value with multiple types</figcaption><pre class="prettyprint lang-js"><code>/**
7381
* Returns the sum of a and b
7482
* @param {Number} a
7583
* @param {Number} b
7684
* @param {Boolean} retArr If set to true, the function will return an array
77-
* @returns {Number|Array} Sum of a and b or an array that contains a, b and the sum of a and b.
85+
* @returns {(Number|Array)} Sum of a and b or an array that contains a, b and the sum of a and b.
7886
*/
7987
function sum(a, b, retArr) {
8088
if (retArr) {
@@ -85,9 +93,14 @@ <h2 id="examples">Examples</h2>
8593
</code></pre>
8694
</figure>
8795
<h2 id="related-links">Related Links</h2>
88-
<p>
89-
<a href="tags-param.html">@param</a>
90-
</p>
96+
<ul>
97+
<li>
98+
<a href="tags-param.html">@param</a>
99+
</li>
100+
<li>
101+
<a href="tags-yields.html">@yields</a>
102+
</li>
103+
</ul>
91104
</article>
92105
<footer>
93106
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">

‎tags-yields.html‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
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="Document the value yielded by a generator function.">
8+
<title>Use JSDoc: @yields</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>@yields</h1>
25+
<h2>Table of Contents</h2>
26+
<ul>
27+
<li>
28+
<a href="#synonyms">Synonyms</a>
29+
</li>
30+
<li>
31+
<a href="#syntax">Syntax</a>
32+
</li>
33+
<li>
34+
<a href="#overview">Overview</a>
35+
</li>
36+
<li>
37+
<a href="#examples">Examples</a>
38+
</li>
39+
<li>
40+
<a href="#related-links">Related Links</a>
41+
</li>
42+
</ul>
43+
<h2 id="synonyms">Synonyms</h2>
44+
<p>
45+
<code>@yield</code>
46+
</p>
47+
<h2 id="syntax">Syntax</h2>
48+
<p><code>@yields [{type}] [description]</code>
49+
</p>
50+
<h2 id="overview">Overview</h2>
51+
<p>The <code>@yields</code> tag documents the value that is yielded by a generator function. This tag is available in JSDoc 3.5.0 and later.</p>
52+
<p>If you are documenting a regular function, use the <a href="tags-returns.html"><code>@returns</code> tag</a> instead of this tag.
53+
</p>
54+
<h2 id="examples">Examples</h2>
55+
<figure>
56+
<figcaption>@yields tag with a type</figcaption><pre class="prettyprint lang-js"><code>/**
57+
* Generate the Fibonacci sequence of numbers.
58+
*
59+
* @yields {number}
60+
*/
61+
function* fibonacci() {}
62+
</code></pre>
63+
</figure>
64+
<figure>
65+
<figcaption>@yields tag with a type and description</figcaption><pre class="prettyprint lang-js"><code>/**
66+
* Generate the Fibonacci sequence of numbers.
67+
*
68+
* @yields {number} The next number in the Fibonacci sequence.
69+
*/
70+
function* fibonacci() {}
71+
</code></pre>
72+
</figure>
73+
<h2 id="related-links">Related Links</h2>
74+
<p>
75+
<a href="tags-returns.html">@returns</a>
76+
</p>
77+
</article>
78+
<footer>
79+
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">
80+
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" />
81+
</a>
82+
<br> Copyright &#169; 2011-2017 the
83+
<a href="https://github.com/jsdoc3/jsdoc3.github.com/contributors">contributors</a> to the JSDoc 3 documentation project.
84+
<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/">
85+
Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
86+
</footer>
87+
<script type="text/javascript">
88+
prettyPrint();
89+
</script>
90+
</body>
91+
92+
</html>

0 commit comments

Comments
 (0)