document yields tag (#169)

jsdoc · Jul 9, 2017 · 805c71c · 805c71c
1 parent b171945
commit 805c71c
Show file tree

Hide file tree

Showing 5 changed files with 181 additions and 13 deletions.
diff --git a/content/en/tags-returns.md b/content/en/tags-returns.md
@@ -5,16 +5,27 @@ synonyms:
     - return
 related:
     - tags-param.html
+    - tags-yields.html
 ---
 
+## Syntax
+
+`@returns [{type}] [description]`
+
+
 ## Overview
 
-The @returns tag documents the value that a function returns.
+The `@returns` tag documents the value that a function returns.
+
+If you are documenting a generator function, use the [`@yields` tag][yields-tag] instead of this
+tag.
+
+[yields-tag]: tags-yields.html
 
 
 ## Examples
 
-{% example "Type of the return value" %}
+{% example "Return value with a type" %}
 
 ```js
 /**
@@ -29,7 +40,7 @@ function sum(a, b) {
 ```
 {% endexample %}
 
-{% example "Type and description of the return value" %}
+{% example "Return value with a type and description" %}
 
 ```js
 /**
@@ -44,15 +55,15 @@ function sum(a, b) {
 ```
 {% endexample %}
 
-{% example "The return value can have different types" %}
+{% example "Return value with multiple types" %}
 
 ```js
 /**
  * Returns the sum of a and b
  * @param {Number} a
  * @param {Number} b
  * @param {Boolean} retArr If set to true, the function will return an array
- * @returns {Number|Array} Sum of a and b or an array that contains a, b and the sum of a and b.
+ * @returns {(Number|Array)} Sum of a and b or an array that contains a, b and the sum of a and b.
  */
 function sum(a, b, retArr) {
     if (retArr) {

diff --git a/content/en/tags-yields.md b/content/en/tags-yields.md
@@ -0,0 +1,50 @@
+---
+tag: yields
+description: Document the value yielded by a generator function.
+synonyms:
+	- yield
+related:
+	- tags-returns.html
+---
+
+## Syntax
+
+`@yields [{type}] [description]`
+
+
+## Overview
+
+The `@yields` tag documents the value that is yielded by a generator function. This tag is available
+in JSDoc 3.5.0 and later.
+
+If you are documenting a regular function, use the [`@returns` tag][returns-tag] instead of this
+tag.
+
+[returns-tag]: tags-returns.html
+
+
+## Examples
+
+{% example "@yields tag with a type" %}
+
+```js
+/**
+ * Generate the Fibonacci sequence of numbers.
+ *
+ * @yields {number}
+ */
+function* fibonacci() {}
+```
+{% endexample %}
+
+{% example "@yields tag with a type and description" %}
+
+```js
+/**
+ * Generate the Fibonacci sequence of numbers.
+ *
+ * @yields {number} The next number in the Fibonacci sequence.
+ */
+function* fibonacci() {}
+```
+{% endexample %}
diff --git a/index.html b/index.html
@@ -190,6 +190,8 @@ <h2 id="block-tags">Block Tags</h2>
       <dd>Distinguish different objects with the same name.</dd>
       <dt><a href="tags-version.html">@version</a></dt>
       <dd>Documents the version number of an item.</dd>
+      <dt><a href="tags-yields.html">@yields</a> (synonyms: @yield)</dt>
+      <dd>Document the value yielded by a generator function.</dd>
     </dl>
     <h2 id="inline-tags">Inline Tags</h2>
     <dl>

diff --git a/tags-returns.html b/tags-returns.html
@@ -27,6 +27,9 @@ <h2>Table of Contents</h2>
       <li>
         <a href="#synonyms">Synonyms</a>
       </li>
+      <li>
+        <a href="#syntax">Syntax</a>
+      </li>
       <li>
         <a href="#overview">Overview</a>
       </li>
@@ -41,11 +44,16 @@ <h2 id="synonyms">Synonyms</h2>
     <p>
       <code>@return</code>
     </p>
+    <h2 id="syntax">Syntax</h2>
+    <p><code>@returns [{type}] [description]</code>
+    </p>
     <h2 id="overview">Overview</h2>
-    <p>The @returns tag documents the value that a function returns.</p>
+    <p>The <code>@returns</code> tag documents the value that a function returns.</p>
+    <p>If you are documenting a generator function, use the <a href="tags-yields.html"><code>@yields</code> tag</a> instead of this tag.
+    </p>
     <h2 id="examples">Examples</h2>
     <figure>
-      <figcaption>Type of the return value</figcaption><pre class="prettyprint lang-js"><code>/**
+      <figcaption>Return value with a type</figcaption><pre class="prettyprint lang-js"><code>/**
  * Returns the sum of a and b
  * @param {Number} a
  * @param {Number} b
@@ -57,7 +65,7 @@ <h2 id="examples">Examples</h2>
 </code></pre>
     </figure>
     <figure>
-      <figcaption>Type and description of the return value</figcaption><pre class="prettyprint lang-js"><code>/**
+      <figcaption>Return value with a type and description</figcaption><pre class="prettyprint lang-js"><code>/**
  * Returns the sum of a and b
  * @param {Number} a
  * @param {Number} b
@@ -69,12 +77,12 @@ <h2 id="examples">Examples</h2>
 </code></pre>
     </figure>
     <figure>
-      <figcaption>The return value can have different types</figcaption><pre class="prettyprint lang-js"><code>/**
+      <figcaption>Return value with multiple types</figcaption><pre class="prettyprint lang-js"><code>/**
  * Returns the sum of a and b
  * @param {Number} a
  * @param {Number} b
  * @param {Boolean} retArr If set to true, the function will return an array
- * @returns {Number|Array} Sum of a and b or an array that contains a, b and the sum of a and b.
+ * @returns {(Number|Array)} Sum of a and b or an array that contains a, b and the sum of a and b.
  */
 function sum(a, b, retArr) {
     if (retArr) {
@@ -85,9 +93,14 @@ <h2 id="examples">Examples</h2>
 </code></pre>
     </figure>
     <h2 id="related-links">Related Links</h2>
-    <p>
-      <a href="tags-param.html">@param</a>
-    </p>
+    <ul>
+      <li>
+        <a href="tags-param.html">@param</a>
+      </li>
+      <li>
+        <a href="tags-yields.html">@yields</a>
+      </li>
+    </ul>
   </article>
   <footer>
     <a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">

diff --git a/tags-yields.html b/tags-yields.html
@@ -0,0 +1,92 @@
+<!DOCTYPE html>
+<!-- THIS IS A GENERATED FILE. DO NOT EDIT. -->
+<html lang="en">
+
+<head>
+  <meta charset="utf-8">
+  <meta name="description" content="Document the value yielded by a generator function.">
+  <title>Use JSDoc: @yields</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>@yields</h1>
+    <h2>Table of Contents</h2>
+    <ul>
+      <li>
+        <a href="#synonyms">Synonyms</a>
+      </li>
+      <li>
+        <a href="#syntax">Syntax</a>
+      </li>
+      <li>
+        <a href="#overview">Overview</a>
+      </li>
+      <li>
+        <a href="#examples">Examples</a>
+      </li>
+      <li>
+        <a href="#related-links">Related Links</a>
+      </li>
+    </ul>
+    <h2 id="synonyms">Synonyms</h2>
+    <p>
+      <code>@yield</code>
+    </p>
+    <h2 id="syntax">Syntax</h2>
+    <p><code>@yields [{type}] [description]</code>
+    </p>
+    <h2 id="overview">Overview</h2>
+    <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>
+    <p>If you are documenting a regular function, use the <a href="tags-returns.html"><code>@returns</code> tag</a> instead of this tag.
+    </p>
+    <h2 id="examples">Examples</h2>
+    <figure>
+      <figcaption>@yields tag with a type</figcaption><pre class="prettyprint lang-js"><code>/**
+ * Generate the Fibonacci sequence of numbers.
+ *
+ * @yields {number}
+ */
+function* fibonacci() {}
+</code></pre>
+    </figure>
+    <figure>
+      <figcaption>@yields tag with a type and description</figcaption><pre class="prettyprint lang-js"><code>/**
+ * Generate the Fibonacci sequence of numbers.
+ *
+ * @yields {number} The next number in the Fibonacci sequence.
+ */
+function* fibonacci() {}
+</code></pre>
+    </figure>
+    <h2 id="related-links">Related Links</h2>
+    <p>
+      <a href="tags-returns.html">@returns</a>
+    </p>
+  </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 &#169; 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>