diff --git a/about-types.html b/about-types.html
new file mode 100644
index 00000000..26588adf
--- /dev/null
+++ b/about-types.html
@@ -0,0 +1,276 @@
+<!DOCTYPE html>
+<!-- THIS IS A GENERATED FILE. DO NOT EDIT. -->
+<html lang="en">
+
+<head>
+ <meta charset="utf-8">
+ <meta name="description" content="The JSDoc type system.">
+ <title>Use JSDoc: Types</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>Types</h1>
+ <p>JSDoc allows you to specify type expressions identifying the type of value that a symbol may contain, a parameter type, or the type of a value returned by a
+ function. These type expressions are specified with the <a href="tags-type.html"><code>@type</code> tag</a>, the <a href="tags-param.html"><code>@param</code> tag</a>,
+ and many others.</p>
+ <h2 id="overview">Overview</h2>
+ <p>A type expression can include the JSDoc namepath to a symbol (for example, <code>myNamespace.MyClass</code>); a built-in JavaScript type (for example, <code>string</code>);
+ or a combination of these. You can use any
+ <a href="https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#type-expressions">Google Closure Compiler type expression</a>,
+ as well as several other formats that are specific to JSDoc.</p>
+ <p>If JSDoc determines that a type expression is invalid, it will display an error message. To force JSDoc to stop running when a type expression is invalid, use
+ the <code>--pedantic</code> option.</p>
+ <p><strong>Note</strong>: Full support for Google Closure Compiler-style type expressions is available in JSDoc 3.2 and later. Earlier versions of JSDoc included
+ partial support for Closure Compiler type expressions.
+ </p>
+ <p>Each type is specified by providing a type expression, using one of the formats described below. Where appropriate, JSDoc will automatically create links to
+ the documentation for other symbols. For example, <code>@type {MyClass}</code> will link to the MyClass documentation if that symbol has been documented.
+ </p>
+ <table id="jsdoc-types" name="jsdoc-types">
+ <tr>
+ <th>Type name</th>
+ <th>Syntax examples</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>Symbol name (name expression)</td>
+ <td>
+ <figure>
+ <pre class="prettyprint"><code>{boolean}
+{myNamespace.MyClass}
+</code></pre>
+ </figure>
+ </td>
+ <td>
+ <p>
+ Specifies the name of a symbol. If you have documented the symbol, JSDoc creates a link to the documentation for that symbol.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ Multiple types (type union)
+ </td>
+ <td>
+ <figure>
+ <figcaption>This can be a number or a boolean.</figcaption>
+ <pre class="prettyprint"><code>{(number|boolean)}
+</code></pre>
+ </figure>
+ </td>
+ <td>
+ <p>
+ This means a value can have one of several types, with the entire list of types enclosed in parentheses and separated by <code>|</code>. The parentheses
+ are suggested for Closure Compiler, but may be omitted in JSDoc.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ Arrays and objects (type applications and record types)
+ </td>
+ <td>
+ <figure>
+ <figcaption>An array of MyClass instances.</figcaption>
+ <pre class="prettyprint"><code>{Array.<MyClass>}
+// or:
+{MyClass[]}
+</code></pre>
+ </figure>
+ <figure>
+ <figcaption>An object with string keys and number values:</figcaption>
+ <pre class="prettyprint"><code>{Object.<string, number>}
+</code></pre>
+ </figure>
+ <figure>
+ <figcaption>An object called 'myObj' with properties 'a' (a number), 'b' (a string), and 'c' (any type).</figcaption>
+ <pre class="prettyprint"><code>{{a: number, b: string, c}} myObj
+// or:
+{Object} myObj
+{number} myObj.a
+{string} myObj.b
+{*} myObj.c
+</code></pre>
+ </figure>
+ </td>
+ <td>
+ <p>
+ JSDoc supports Closure Compiler's syntax for defining array and object types.
+ <p>
+ <p>
+ You can also indicate an array by appending <code>[]</code> to the type that is contained in the array. For example, the expression <code>string[]</code> indicates an array of strings.
+ </p>
+ <p>
+ For objects that have a known set of properties, you can use Closure Compiler's syntax for documenting record types. As an alternative, you can document each
+ property individually, which enables you to provide more detailed information about each property.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ Nullable type
+ </td>
+ <td>
+ <figure>
+ <figcaption>A number or null.</figcaption>
+ <pre class="prettyprint"><code>{?number}
+</code></pre>
+ </figure>
+ </td>
+ <td>
+ <p>
+ This indicates that the type is either the specified type, or <code>null</code>.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ Non-nullable type
+ </td>
+ <td>
+ <figure>
+ <figcaption>A number, but never null.</figcaption>
+ <pre class="prettyprint"><code>{!number}
+</code></pre>
+ </figure>
+ </td>
+ <td>
+ <p>
+ Indicates that the value is of the specified type, but cannot be <code>null</code>.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ Variable number of that type
+ </td>
+ <td>
+ <figure>
+ <figcaption>This function accepts a variable number of numeric parameters.</figcaption>
+ <pre class="prettyprint"><code>@param {...number} num
+</code></pre>
+ </figure>
+ </td>
+ <td>
+ <p>
+ Indicates that the function accepts a variable number of parameters, and specifies a type for the parameters. For example:
+ </p>
+ <figure>
+ <pre class="prettyprint"><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>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ Optional parameter
+ </td>
+ <td>
+ <figure>
+ <figcaption>An optional parameter named foo.</figcaption>
+ <pre class="prettyprint"><code>@param {number} [foo]
+// or:
+@param {number=} foo
+</code></pre>
+ </figure>
+ <figure>
+ <figcaption>An optional parameter foo with default value 1.</figcaption>
+ <pre class="prettyprint"><code>@param {number} [foo=1]
+</code></pre>
+ </figure>
+ </td>
+ <td>
+ <p>
+ Indicates that the parameter is optional. When using JSDoc's syntax for optional parameters, you can also indicate the value that will be used if a parameter
+ is omitted.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ Callbacks
+ </td>
+ <td>
+ <figure>
+ <pre class="prettyprint"><code>/**
+ * @callback myCallback
+ * @param {number} x - ...
+ */
+
+/** @type {myCallback} */
+var cb;
+</code></pre>
+ </figure>
+ </td>
+ <td>
+ <p>
+ Document a callback using the <a href="tags-callback.html"><code>@callback</code></a> tag. The syntax is identical to the <code>@typedef</code> tag,
+ except that a callback's type is always
+ <code>function</code>.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ Type definitions
+ </td>
+ <td>
+ <figure>
+ <figcaption>Documenting a type with properties 'id', 'name', 'age'.</figcaption>
+ <pre class="prettyprint"><code>/**
+ * @typedef PropertiesHash
+ * @type {object}
+ * @property {string} id - an ID.
+ * @property {string} name - your name.
+ * @property {number} age - your age.
+ */
+
+/** @type {PropertiesHash} */
+var props;
+</code></pre>
+ </figure>
+ </td>
+ <td>
+ <p>
+ You can document complex types using the <a href="tags-typedef.html">@typedef</a> tag, then refer to the type definition elsewhere in your documentation.
+ </p>
+ </td>
+ </tr>
+ </table>
+ </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>
\ No newline at end of file
diff --git a/content/en/about-types.md b/content/en/about-types.md
new file mode 100644
index 00000000..24320437
--- /dev/null
+++ b/content/en/about-types.md
@@ -0,0 +1,261 @@
+---
+title: Types
+description: The JSDoc type system.
+---
+
+JSDoc allows you to specify type expressions identifying the type of value that a symbol may
+contain, a parameter type, or the type of a value returned by a function. These type expressions
+are specified with the [`@type` tag][type-tag], the [`@param` tag][param-tag], and many others.
+
+[type-tag]: tags-type.html
+[param-tag]: tags-param.html
+
+## Overview
+
+A type expression can include the JSDoc namepath to a symbol (for example, `myNamespace.MyClass`); a
+built-in JavaScript type (for example, `string`); or a combination of these. You can use any
+[Google Closure Compiler type expression][closure], as well as several other formats that are
+specific to JSDoc.
+
+If JSDoc determines that a type expression is invalid, it will display an error message. To force JSDoc to stop running when a type expression is invalid, use the `--pedantic` option.
+
+**Note**: Full support for Google Closure Compiler-style type expressions is available
+in JSDoc 3.2 and later. Earlier versions of JSDoc included partial support for Closure Compiler type
+expressions.
+
+Each type is specified by providing a type expression, using one of the formats described below.
+Where appropriate, JSDoc will automatically create links to the documentation for other symbols. For
+example, `@type {MyClass}` will link to the MyClass documentation if that symbol has been
+documented.
+
+<table id="jsdoc-types" name="jsdoc-types">
+<tr>
+ <th>Type name</th>
+ <th>Syntax examples</th>
+ <th>Description</th>
+</tr>
+
+<tr>
+ <td>Symbol name (name expression)</td>
+ <td>
+{% example %}
+<pre class="prettyprint"><code>{boolean}
+{myNamespace.MyClass}
+</code></pre>
+{% endexample %}
+ </td>
+ <td>
+ <p>
+ Specifies the name of a symbol. If you have documented the symbol, JSDoc creates a link to the
+ documentation for that symbol.
+ </p>
+ </td>
+</tr>
+
+<tr>
+ <td>
+ Multiple types (type union)
+ </td>
+ <td>
+{% example "This can be a number or a boolean." %}
+<pre class="prettyprint"><code>{(number|boolean)}
+</code></pre>
+{% endexample %}
+ </td>
+ <td>
+ <p>
+ This means a value can have one of several types, with the entire list of types enclosed in
+ parentheses and separated by <code>|</code>. The parentheses are suggested for Closure Compiler,
+ but may be omitted in JSDoc.
+ </p>
+ </td>
+</tr>
+
+<tr>
+ <td>
+ Arrays and objects (type applications and record types)
+ </td>
+ <td>
+{% example "An array of MyClass instances." %}
+<pre class="prettyprint"><code>{Array.<MyClass>}
+// or:
+{MyClass[]}
+</code></pre>
+{% endexample %}
+
+{% example "An object with string keys and number values:" %}
+<pre class="prettyprint"><code>{Object.<string, number>}
+</code></pre>
+{% endexample %}
+
+{% example "An object called 'myObj' with properties 'a' (a number), 'b' (a string), and 'c' (any type)." %}
+<pre class="prettyprint"><code>{{a: number, b: string, c}} myObj
+// or:
+{Object} myObj
+{number} myObj.a
+{string} myObj.b
+{*} myObj.c
+</code></pre>
+{% endexample %}
+ </td>
+ <td><p>
+ JSDoc supports Closure Compiler's syntax for defining array and object types.
+ <p>
+ <p>
+ You can also indicate an array by appending <code>[]</code> to the type that is contained in the
+ array. For example, the expression <code>string[]</code> indicates an array of strings.
+ </p>
+ <p>
+ For objects that have a known set of properties, you can use Closure Compiler's syntax for
+ documenting record types. As an alternative, you can document each property individually, which
+ enables you to provide more detailed information about each property.
+ </p>
+ </td>
+</tr>
+
+<tr>
+ <td>
+ Nullable type
+ </td>
+ <td>
+{% example "A number or null." %}
+<pre class="prettyprint"><code>{?number}
+</code></pre>
+{% endexample %}
+ </td>
+ <td>
+ <p>
+ This indicates that the type is either the specified type, or <code>null</code>.
+ </p>
+ </td>
+</tr>
+
+<tr>
+ <td>
+ Non-nullable type
+ </td>
+ <td>
+{% example "A number, but never null." %}
+<pre class="prettyprint"><code>{!number}
+</code></pre>
+{% endexample %}
+ </td>
+ <td>
+ <p>
+ Indicates that the value is of the specified type, but cannot be <code>null</code>.
+ </p>
+ </td>
+</tr>
+
+<tr>
+ <td>
+ Variable number of that type
+ </td>
+ <td>
+{% example "This function accepts a variable number of numeric parameters." %}
+<pre class="prettyprint"><code>@param {...number} num
+</code></pre>
+{% endexample %}
+ </td>
+ <td>
+ <p>
+ Indicates that the function accepts a variable number of parameters, and specifies a type for the
+ parameters. For example:
+ </p>
+{% example %}
+<pre class="prettyprint"><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>
+{% endexample %}
+ </td>
+</tr>
+
+<tr>
+ <td>
+ Optional parameter
+ </td>
+ <td>
+{% example "An optional parameter named foo." %}
+<pre class="prettyprint"><code>@param {number} [foo]
+// or:
+@param {number=} foo
+</code></pre>
+{% endexample %}
+
+{% example "An optional parameter foo with default value 1." %}
+<pre class="prettyprint"><code>@param {number} [foo=1]
+</code></pre>
+{% endexample %}
+ </td>
+ <td>
+ <p>
+ Indicates that the parameter is optional. When using JSDoc's syntax for optional parameters, you
+ can also indicate the value that will be used if a parameter is omitted.
+ </p>
+ </td>
+</tr>
+
+<tr>
+ <td>
+ Callbacks
+ </td>
+ <td>
+{% example %}
+<pre class="prettyprint"><code>/**
+ * @callback myCallback
+ * @param {number} x - ...
+ */
+
+/** @type {myCallback} */
+var cb;
+</code></pre>
+{% endexample %}
+ </td>
+ <td>
+ <p>
+ Document a callback using the <a href="tags-callback.html"><code>@callback</code></a> tag. The
+ syntax is identical to the <code>@typedef</code> tag, except that a callback's type is always
+ <code>function</code>.
+ </p>
+ </td>
+</tr>
+
+<tr>
+ <td>
+ Type definitions
+ </td>
+ <td>
+{% example "Documenting a type with properties 'id', 'name', 'age'." %}
+<pre class="prettyprint"><code>/**
+ * @typedef PropertiesHash
+ * @type {object}
+ * @property {string} id - an ID.
+ * @property {string} name - your name.
+ * @property {number} age - your age.
+ */
+
+/** @type {PropertiesHash} */
+var props;
+</code></pre>
+{% endexample %}
+ </td>
+ <td>
+ <p>
+ You can document complex types using the <a href="tags-typedef.html">@typedef</a> tag, then refer
+ to the type definition elsewhere in your documentation.
+ </p>
+ </td>
+</tr>
+</table>
+
+[closure]: https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#type-expressions
+[param-tag]: tags-param.html
diff --git a/content/en/tags-param.md b/content/en/tags-param.md
index 1d82b3d0..ac46ba71 100644
--- a/content/en/tags-param.md
+++ b/content/en/tags-param.md
@@ -22,13 +22,13 @@ The parameter type can be a built-in JavaScript type, such as `string` or `Objec
[JSDoc namepath][namepath] 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 [`@type` tag documentation][type-tag] for details.
+any type; see the [types documentation][about-types] for details.
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.
[namepath]: about-namepaths.html
-[type-tag]: tags-type.html
+[about-types]: about-types.html
## Examples
@@ -193,7 +193,7 @@ function sayHello(somebody) {
### Multiple types and repeatable parameters
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
-[`@type` tag documentation][type-tag] for details about the type expressions that JSDoc supports.
+[types documentation][about-types] for details about the type expressions that JSDoc supports.
{% example "Allows one type OR another type (type union)" %}
@@ -267,4 +267,4 @@ function doSomethingAsynchronously(cb) {
{% endexample %}
[callback-tag]: tags-callback.html
-[type-tag]: tags-type.html
+[about-types]: about-types.html
diff --git a/content/en/tags-type.md b/content/en/tags-type.md
index 3c6cace4..2c0de641 100644
--- a/content/en/tags-type.md
+++ b/content/en/tags-type.md
@@ -15,257 +15,17 @@ related:
## Overview
-The @type tag allows you to provide a type expression identifying the type of value that a symbol
-may contain, or the type of value returned by a function. You can also include type expressions with
-many other JSDoc tags, such as the [@param tag][param-tag].
+The `@type` tag allows you to provide a type expression identifying the type of value that a symbol
+may contain. For function parameters, you can also use an inline `@type` tag to identify its type.
-A type expression can include the JSDoc namepath to a symbol (for example, `myNamespace.MyClass`); a
-built-in JavaScript type (for example, `string`); or a combination of these. You can use any
-[Google Closure Compiler type expression][closure], as well as several other formats that are
-specific to JSDoc.
-
-If JSDoc determines that a type expression is invalid, it will display an error and stop running.
-You can turn this error into a warning by running JSDoc with the `--lenient` option.
-
-**Note**: Full support for Google Closure Compiler-style type expressions is available
-in JSDoc 3.2 and later. Earlier versions of JSDoc included partial support for Closure Compiler type
-expressions.
-
-Each type is specified by providing a type expression, using one of the formats described below.
-Where appropriate, JSDoc will automatically create links to the documentation for other symbols. For
-example, `@type {MyClass}` will link to the MyClass documentation if that symbol has been
-documented.
-
-<table id="jsdoc-types" name="jsdoc-types">
-<tr>
- <th>Type name</th>
- <th>Syntax examples</th>
- <th>Description</th>
-</tr>
-
-<tr>
- <td>Symbol name (name expression)</td>
- <td>
-{% example %}
-<pre class="prettyprint"><code>{boolean}
-{myNamespace.MyClass}
-</code></pre>
-{% endexample %}
- </td>
- <td>
- <p>
- Specifies the name of a symbol. If you have documented the symbol, JSDoc creates a link to the
- documentation for that symbol.
- </p>
- </td>
-</tr>
-
-<tr>
- <td>
- Multiple types (type union)
- </td>
- <td>
-{% example "This can be a number or a boolean." %}
-<pre class="prettyprint"><code>{(number|boolean)}
-</code></pre>
-{% endexample %}
- </td>
- <td>
- <p>
- This means a value can have one of several types, with the entire list of types enclosed in
- parentheses and separated by <code>|</code>.
- </p>
- </td>
-</tr>
-
-<tr>
- <td>
- Arrays and objects (type applications and record types)
- </td>
- <td>
-{% example "An array of MyClass instances." %}
-<pre class="prettyprint"><code>{Array.<MyClass>}
-// or:
-{MyClass[]}
-</code></pre>
-{% endexample %}
-
-{% example "An object with string keys and number values:" %}
-<pre class="prettyprint"><code>{Object.<string, number>}
-</code></pre>
-{% endexample %}
-
-{% example "An object called 'myObj' with properties 'a' (a number), 'b' (a string) and 'c' (any type)." %}
-<pre class="prettyprint"><code>{{a: number, b: string, c}} myObj
-// or:
-{Object} myObj
-{number} myObj.a
-{string} myObj.b
-{*} myObj.c
-</code></pre>
-{% endexample %}
- </td>
- <td><p>
- JSDoc supports Closure Compiler's syntax for defining array and object types.
- <p>
- <p>
- You can also indicate an array by appending <code>[]</code> to the type that is contained in the
- array. For example, the expression <code>string[]</code> indicates an array of strings.
- </p>
- <p>
- For objects that have a known set of properties, you can use Closure Compiler's syntax for
- documenting record types. You can document each property individually, which enables you to
- provide more detailed information about each property.
- </p>
- </td>
-</tr>
-
-<tr>
- <td>
- Nullable type
- </td>
- <td>
-{% example "A number or null." %}
-<pre class="prettyprint"><code>{?number}
-</code></pre>
-{% endexample %}
- </td>
- <td>
- <p>
- This indicates that the type is either the specified type, or <code>null</code>.
- </p>
- </td>
-</tr>
-
-<tr>
- <td>
- Non-nullable type
- </td>
- <td>
-{% example "A number, but never null." %}
-<pre class="prettyprint"><code>{!number}
-</code></pre>
-{% endexample %}
- </td>
- <td>
- <p>
- Indicates that the value is of the specified type, but cannot be <code>null</code>.
- </p>
- </td>
-</tr>
-
-<tr>
- <td>
- Variable number of that type
- </td>
- <td>
-{% example "This function accepts a variable number of numeric parameters." %}
-<pre class="prettyprint"><code>@param {...number} num
-</code></pre>
-{% endexample %}
- </td>
- <td>
- <p>
- Indicates that the function accepts a variable number of parameters, and specifies a type for the
- parameters. For example:
- </p>
-{% example %}
-<pre class="prettyprint"><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>
-{% endexample %}
- </td>
-</tr>
-
-<tr>
- <td>
- Optional parameter
- </td>
- <td>
-{% example "An optional parameter named foo." %}
-<pre class="prettyprint"><code>@param {number} [foo]
-// or:
-@param {number=} foo
-</code></pre>
-{% endexample %}
-
-{% example "An optional parameter foo with default value 1." %}
-<pre class="prettyprint"><code>@param {number} [foo=1]
-</code></pre>
-{% endexample %}
- </td>
- <td>
- <p>
- Indicates that the parameter is optional. When using JSDoc's syntax for optional parameters, you
- can also indicate the value that will be used if a parameter is omitted.
- </p>
- </td>
-</tr>
-
-<tr>
- <td>
- Callbacks
- </td>
- <td>
-{% example %}
-<pre class="prettyprint"><code>/**
- * @callback myCallback
- * @param {number} x - ...
- */
-
-/** @type {myCallback} */
-var cb;
-</code></pre>
-{% endexample %}
- </td>
- <td>
- <p>
- Document a callback using the <a href="tags-callback.html">@callback</a> tag. The syntax is
- identical to the @typedef tag, except that a callback's type is always "function."
- </p>
- </td>
-</tr>
-
-<tr>
- <td>
- Type definitions
- </td>
- <td>
-{% example "Documenting a type with properties 'id', 'name', 'age'." %}
-<pre class="prettyprint"><code>/**
- * @typedef PropertiesHash
- * @type {object}
- * @property {string} id - an ID.
- * @property {string} name - your name.
- * @property {number} age - your age.
- */
-
-/** @type {PropertiesHash} */
-var props;
-</code></pre>
-{% endexample %}
- </td>
- <td>
- <p>
- You can document complex types using the <a href="tags-typedef.html">@typedef</a> tag, then refer
- to the type definition elsewhere in your documentation.
- </p>
- </td>
-</tr>
-</table>
-
-[closure]: https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#type-expressions
-[param-tag]: tags-param.html
+The parameter type can be a built-in JavaScript type, such as `number` or `Object`, or a
+[JSDoc namepath][namepath] 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 further properties of the type; see the
+[types documentation][about-types] for details.
+[namepath]: about-namepaths.html
+[about-types]: about-types.html
## Examples
@@ -297,3 +57,13 @@ var FOO = 1;
var FOO = 1;
```
{% endexample %}
+
+The Google Closure Compiler also allows the use of `@type` to "cast" or change the type of a
+variable so that it confirms to what is needed by a function parameter or assignment. The
+surrounding parentheses are required.
+
+{% example "Cast a variable to a specific type." }
+
+```js
+method(/** @type {Array<string>} */ (value));
+```
\ No newline at end of file
diff --git a/data/toc.json b/data/toc.json
index 2d52e8dd..7b67520d 100644
--- a/data/toc.json
+++ b/data/toc.json
@@ -6,6 +6,9 @@
{
"filename": "about-namepaths.html"
},
+ {
+ "filename": "about-types.html"
+ },
{
"filename": "about-commandline.html"
},
diff --git a/index.html b/index.html
index 59360d93..65101dad 100644
--- a/index.html
+++ b/index.html
@@ -28,6 +28,8 @@ <h2>Getting Started</h2>
<dd>A quick-start to documenting JavaScript with JSDoc.</dd>
<dt><a href="about-namepaths.html">Using namepaths with JSDoc 3</a></dt>
<dd>A guide to using namepaths with JSDoc 3.</dd>
+ <dt><a href="about-types.html">Types</a></dt>
+ <dd>The JSDoc type system.</dd>
<dt><a href="about-commandline.html">Command-line arguments to JSDoc</a></dt>
<dd>About command-line arguments to JSDoc.</dd>
<dt><a href="about-configuring-jsdoc.html">Configuring JSDoc with a configuration file</a></dt>
@@ -217,8 +219,7 @@ <h2>Contribute</h2>
</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>
+ <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/">
diff --git a/tags-param.html b/tags-param.html
index 11eafc5c..2f4b97ec 100644
--- a/tags-param.html
+++ b/tags-param.html
@@ -70,7 +70,7 @@ <h2 id="overview">Overview</h2>
<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>
+ or can accept any type; see the <a href="about-types.html">types 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>
@@ -83,8 +83,7 @@ <h3 id="names-types-and-descriptions">Names, types, and descriptions</h3>
function sayHello(somebody) {
alert('Hello ' + somebody);
}
-</code></pre>
- </figure>
+</code></pre></figure>
<figure>
<figcaption>Name and type</figcaption><pre class="prettyprint lang-js"><code>/**
* @param {string} somebody
@@ -92,8 +91,7 @@ <h3 id="names-types-and-descriptions">Names, types, and descriptions</h3>
function sayHello(somebody) {
alert('Hello ' + somebody);
}
-</code></pre>
- </figure>
+</code></pre></figure>
<figure>
<figcaption>Name, type, and description</figcaption><pre class="prettyprint lang-js"><code>/**
* @param {string} somebody Somebody's name.
@@ -101,8 +99,7 @@ <h3 id="names-types-and-descriptions">Names, types, and descriptions</h3>
function sayHello(somebody) {
alert('Hello ' + somebody);
}
-</code></pre>
- </figure>
+</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>/**
@@ -111,8 +108,7 @@ <h3 id="names-types-and-descriptions">Names, types, and descriptions</h3>
function sayHello(somebody) {
alert('Hello ' + somebody);
}
-</code></pre>
- </figure>
+</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
@@ -151,8 +147,7 @@ <h3 id="parameters-with-properties">Parameters with properties</h3>
Project.prototype.assign = function(employees) {
// ...
};
-</code></pre>
- </figure>
+</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>
@@ -165,8 +160,7 @@ <h3 id="optional-parameters-and-default-values">Optional parameters and default
}
alert('Hello ' + somebody);
}
-</code></pre>
- </figure>
+</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.
@@ -177,8 +171,7 @@ <h3 id="optional-parameters-and-default-values">Optional parameters and default
}
alert('Hello ' + somebody);
}
-</code></pre>
- </figure>
+</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.
@@ -189,12 +182,11 @@ <h3 id="optional-parameters-and-default-values">Optional parameters and default
}
alert('Hello ' + somebody);
}
-</code></pre>
- </figure>
+</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>
+ <a href="about-types.html">types 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.
@@ -207,8 +199,7 @@ <h3 id="multiple-types-and-repeatable-parameters">Multiple types and repeatable
}
alert('Hello ' + somebody);
}
-</code></pre>
- </figure>
+</code></pre></figure>
<figure>
<figcaption>Allows any type</figcaption><pre class="prettyprint lang-js"><code>/**
* @param {*} somebody - Whatever you want.
@@ -216,8 +207,7 @@ <h3 id="multiple-types-and-repeatable-parameters">Multiple types and repeatable
function sayHello(somebody) {
console.log('Hello ' + JSON.stringify(somebody));
}
-</code></pre>
- </figure>
+</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.
@@ -230,8 +220,7 @@ <h3 id="multiple-types-and-repeatable-parameters">Multiple types and repeatable
}
return t;
}
-</code></pre>
- </figure>
+</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>
@@ -251,8 +240,7 @@ <h3 id="callback-functions">Callback functions</h3>
function doSomethingAsynchronously(cb) {
// code
};
-</code></pre>
- </figure>
+</code></pre></figure>
<h2 id="related-links">Related Links</h2>
<ul>
<li>
@@ -271,8 +259,7 @@ <h2 id="related-links">Related Links</h2>
</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>
+ <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/">
diff --git a/tags-type.html b/tags-type.html
index 37f4637b..4b45775f 100644
--- a/tags-type.html
+++ b/tags-type.html
@@ -38,250 +38,21 @@ <h2>Table of Contents</h2>
</li>
</ul>
<h2 id="syntax">Syntax</h2>
- <p><code>@type {typeName}</code>
- </p>
+ <p><code>@type {typeName}</code></p>
<h2 id="overview">Overview</h2>
- <p>The @type tag allows you to provide a type expression identifying the type of value that a symbol may contain, or the type of value returned by a function. You
- can also include type expressions with many other JSDoc tags, such as the <a href="tags-param.html">@param tag</a>.</p>
- <p>A type expression can include the JSDoc namepath to a symbol (for example, <code>myNamespace.MyClass</code>); a built-in JavaScript type (for example, <code>string</code>);
- or a combination of these. You can use any
- <a href="https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#type-expressions">Google Closure Compiler type expression</a>,
- as well as several other formats that are specific to JSDoc.</p>
- <p>If JSDoc determines that a type expression is invalid, it will display an error and stop running. You can turn this error into a warning by running JSDoc with
- the <code>--lenient</code> option.</p>
- <p><strong>Note</strong>: Full support for Google Closure Compiler-style type expressions is available in JSDoc 3.2 and later. Earlier versions of JSDoc included
- partial support for Closure Compiler type expressions.
- </p>
- <p>Each type is specified by providing a type expression, using one of the formats described below. Where appropriate, JSDoc will automatically create links to
- the documentation for other symbols. For example, <code>@type {MyClass}</code> will link to the MyClass documentation if that symbol has been documented.
- </p>
- <table id="jsdoc-types" name="jsdoc-types">
- <tr>
- <th>Type name</th>
- <th>Syntax examples</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>Symbol name (name expression)</td>
- <td>
- <figure>
- <pre class="prettyprint"><code>{boolean}
-{myNamespace.MyClass}
-</code></pre>
- </figure>
- </td>
- <td>
- <p>
- Specifies the name of a symbol. If you have documented the symbol, JSDoc creates a link to the documentation for that symbol.
- </p>
- </td>
- </tr>
- <tr>
- <td>
- Multiple types (type union)
- </td>
- <td>
- <figure>
- <figcaption>This can be a number or a boolean.</figcaption>
- <pre class="prettyprint"><code>{(number|boolean)}
-</code></pre>
- </figure>
- </td>
- <td>
- <p>
- This means a value can have one of several types, with the entire list of types enclosed in parentheses and separated by <code>|</code>.
- </p>
- </td>
- </tr>
- <tr>
- <td>
- Arrays and objects (type applications and record types)
- </td>
- <td>
- <figure>
- <figcaption>An array of MyClass instances.</figcaption>
- <pre class="prettyprint"><code>{Array.<MyClass>}
-// or:
-{MyClass[]}
-</code></pre>
- </figure>
- <figure>
- <figcaption>An object with string keys and number values:</figcaption>
- <pre class="prettyprint"><code>{Object.<string, number>}
-</code></pre>
- </figure>
- <figure>
- <figcaption>An object called 'myObj' with properties 'a' (a number), 'b' (a string) and 'c' (any type).</figcaption>
- <pre class="prettyprint"><code>{{a: number, b: string, c}} myObj
-// or:
-{Object} myObj
-{number} myObj.a
-{string} myObj.b
-{<em>} myObj.c
-</code></pre>
- </figure>
- </td>
- <td>
- <p>
- JSDoc supports Closure Compiler's syntax for defining array and object types.
- <p>
- <p>
- You can also indicate an array by appending <code>[]</code> to the type that is contained in the array. For example, the expression <code>string[]</code> indicates an array of strings.
- </p>
- <p>
- For objects that have a known set of properties, you can use Closure Compiler's syntax for documenting record types. You can document each property individually,
- which enables you to provide more detailed information about each property.
- </p>
- </td>
- </tr>
- <tr>
- <td>
- Nullable type
- </td>
- <td>
- <figure>
- <figcaption>A number or null.</figcaption>
- <pre class="prettyprint"><code>{?number}
-</code></pre>
- </figure>
- </td>
- <td>
- <p>
- This indicates that the type is either the specified type, or <code>null</code>.
- </p>
- </td>
- </tr>
- <tr>
- <td>
- Non-nullable type
- </td>
- <td>
- <figure>
- <figcaption>A number, but never null.</figcaption>
- <pre class="prettyprint"><code>{!number}
-</code></pre>
- </figure>
- </td>
- <td>
- <p>
- Indicates that the value is of the specified type, but cannot be <code>null</code>.
- </p>
- </td>
- </tr>
- <tr>
- <td>
- Variable number of that type
- </td>
- <td>
- <figure>
- <figcaption>This function accepts a variable number of numeric parameters.</figcaption>
- <pre class="prettyprint"><code>@param {...number} num
-</code></pre>
- </figure>
- </td>
- <td>
- <p>
- Indicates that the function accepts a variable number of parameters, and specifies a type for the parameters. For example:
- </p>
- <figure>
- <pre class="prettyprint"><code>/**
- </em> Returns the sum of all numbers passed to the function.
- <em> @param {...number} num A positive or negative number
- </em>/
-function sum(num) {
- var i=0, n=arguments.length, t=0;
- for (; i<n; i++) {
- t += arguments[i];
- }
- return t;
-}
-</code></pre>
- </figure>
- </td>
- </tr>
- <tr>
- <td>
- Optional parameter
- </td>
- <td>
- <figure>
- <figcaption>An optional parameter named foo.</figcaption>
- <pre class="prettyprint"><code>@param {number} [foo]
-// or:
-@param {number=} foo
-</code></pre>
- </figure>
- <figure>
- <figcaption>An optional parameter foo with default value 1.</figcaption>
- <pre class="prettyprint"><code>@param {number} [foo=1]
-</code></pre>
- </figure>
- </td>
- <td>
- <p>
- Indicates that the parameter is optional. When using JSDoc's syntax for optional parameters, you can also indicate the value that will be used if a parameter
- is omitted.
- </p>
- </td>
- </tr>
- <tr>
- <td>
- Callbacks
- </td>
- <td>
- <figure>
- <pre class="prettyprint"><code>/<strong>
- <em> @callback myCallback
- </em> @param {number} x - ...
- */
-
-/</strong> @type {myCallback} <em>/
-var cb;
-</code></pre>
- </figure>
- </td>
- <td>
- <p>
- Document a callback using the <a href="tags-callback.html">@callback</a> tag. The syntax is identical to the @typedef tag, except that a callback's
- type is always "function."
- </p>
- </td>
- </tr>
- <tr>
- <td>
- Type definitions
- </td>
- <td>
- <figure>
- <figcaption>Documenting a type with properties 'id', 'name', 'age'.</figcaption>
- <pre class="prettyprint"><code>/**
- </em> @typedef PropertiesHash
- <em> @type {object}
- </em> @property {string} id - an ID.
- <em> @property {string} name - your name.
- </em> @property {number} age - your age.
- <em>/
-
-/** @type {PropertiesHash} </em>/
-var props;
-</code></pre>
- </figure>
- </td>
- <td>
- <p>
- You can document complex types using the <a href="tags-typedef.html">@typedef</a> tag, then refer to the type definition elsewhere in your documentation.
- </p>
- </td>
- </tr>
- </table>
+ <p>The <code>@type</code> tag allows you to provide a type expression identifying the type of value that a symbol may contain. For function parameters, you can
+ also use an inline <code>@type</code> tag to identify its type.</p>
+ <p>The parameter type can be a built-in JavaScript type, such as <code>number</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 further properties of the type; see the
+ <a href="about-types.html">types documentation</a> for details.</p>
<h2 id="examples">Examples</h2>
<figure>
<figcaption>Example</figcaption><pre class="prettyprint lang-js"><code>/** @type {(string|Array.<string>)} */
var foo;
/** @type {number} */
var bar = 1;
-</code></pre>
- </figure>
+</code></pre></figure>
<p>In many cases, you can include a type expression as part of another tag, rather than including a separate @type tag in your JSDoc comment.</p>
<figure>
<figcaption>Type expressions can accompany many tags.</figcaption><pre class="prettyprint lang-js"><code>/**
@@ -294,8 +65,12 @@ <h2 id="examples">Examples</h2>
/** @const {number} */
var FOO = 1;
+</code></pre></figure>
+ <p>The Google Closure Compiler also allows the use of <code>@type</code> to "cast" or change the type of a variable so that it confirms to what is needed
+ by a function parameter or assignment. The surrounding parentheses are required.</p>
+ <p>{% example "Cast a variable to a specific type." }</p>
+ <pre class="prettyprint lang-js"><code>method(/** @type {Array<string>} */ (value));
</code></pre>
- </figure>
<h2 id="related-links">Related Links</h2>
<ul>
<li>
@@ -314,8 +89,7 @@ <h2 id="related-links">Related Links</h2>
</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>
+ <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/">