document async tag (#158)

hegemonic · hegemonic · commit dda184335220 · 2017-07-08T15:03:19.000-07:00
diff --git a/content/en/tags-async.md b/content/en/tags-async.md
@@ -0,0 +1,43 @@
+---
+tag: async
+description: Indicate that a function is asynchronous.
+---
+
+## Syntax
+
+`@async`
+
+
+## Overview
+
+The `@async` tag indicates that a function is [asynchronous][async-function], meaning that it
+was declared using the syntax `async function foo() {}`. Do not use this tag for other types of
+asynchronous functions, such as functions that provide a callback. This tag is available in JSDoc
+3.5.0 and later.
+
+In general, you do not need to use this tag, because JSDoc automatically detects asynchronous
+functions and identifies them in the generated documentation. However, if you are writing a virtual
+comment for an asynchronous function that does not appear in your code, you can use this tag to
+tell JSDoc that the function is asynchronous.
+
+[async-function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function
+
+
+## Example
+
+The following example shows a virtual comment that uses the `@async` tag:
+
+{% example "Virtual comment with @async tag" %}
+
+```js
+/**
+ * Download data from the specified URL.
+ *
+ * @async
+ * @function downloadData
+ * @param {string} url - The URL to download from.
+ * @return {Promise&lt;string>} The data from the URL.
+ */
+```
+
+{% endexample %}
diff --git a/index.html b/index.html
@@ -68,6 +68,8 @@ <h2 id="block-tags">Block Tags</h2>
       <dd>Specify the access level of this member (private, public, or protected).</dd>
       <dt><a href="tags-alias.html">@alias</a></dt>
       <dd>Treat a member as if it had a different name.</dd>
+      <dt><a href="tags-async.html">@async</a></dt>
+      <dd>Indicate that a function is asynchronous.</dd>
       <dt><a href="tags-augments.html">@augments</a> (synonyms: @extends)</dt>
       <dd>Indicate that a symbol inherits from, and adds to, a parent symbol.</dd>
       <dt><a href="tags-author.html">@author</a></dt>
diff --git a/tags-async.html b/tags-async.html
@@ -0,0 +1,75 @@
+<!DOCTYPE html>
+<!-- THIS IS A GENERATED FILE. DO NOT EDIT. -->
+<html lang="en">
+
+<head>
+  <meta charset="utf-8">
+  <meta name="description" content="Indicate that a function is asynchronous.">
+  <title>Use JSDoc: @async</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>@async</h1>
+    <h2>Table of Contents</h2>
+    <ul>
+      <li>
+        <a href="#syntax">Syntax</a>
+      </li>
+      <li>
+        <a href="#overview">Overview</a>
+      </li>
+      <li>
+        <a href="#example">Example</a>
+      </li>
+    </ul>
+    <h2 id="syntax">Syntax</h2>
+    <p><code>@async</code>
+    </p>
+    <h2 id="overview">Overview</h2>
+    <p>The <code>@async</code> tag indicates that a function is <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function">asynchronous</a>,
+      meaning that it was declared using the syntax <code>async function foo() {}</code>. Do not use this tag for other types of asynchronous functions, such as
+      functions that provide a callback. This tag is available in JSDoc 3.5.0 and later.</p>
+    <p>In general, you do not need to use this tag, because JSDoc automatically detects asynchronous functions and identifies them in the generated documentation. However,
+      if you are writing a virtual comment for an asynchronous function that does not appear in your code, you can use this tag to tell JSDoc that the function is
+      asynchronous.</p>
+    <h2 id="example">Example</h2>
+    <p>The following example shows a virtual comment that uses the <code>@async</code> tag:</p>
+    <figure>
+      <figcaption>Virtual comment with @async tag</figcaption><pre class="prettyprint lang-js"><code>/**
+ * Download data from the specified URL.
+ *
+ * @async
+ * @function downloadData
+ * @param {string} url - The URL to download from.
+ * @return {Promise&lt;string>} The data from the URL.
+ */
+</code></pre>
+    </figure>
+  </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>
