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, the @param tag,
+ and many others.
+
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,
+ 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.
+
+
+
+
Type name
+
Syntax examples
+
Description
+
+
+
Symbol name (name expression)
+
+
+
{boolean}
+{myNamespace.MyClass}
+
+
+
+
+
+ Specifies the name of a symbol. If you have documented the symbol, JSDoc creates a link to the documentation for that symbol.
+
+
+
+
+
+ Multiple types (type union)
+
+
+
+ This can be a number or a boolean.
+
{(number|boolean)}
+
+
+
+
+
+ This means a value can have one of several types, with the entire list of types enclosed in parentheses and separated by |. The parentheses
+ are suggested for Closure Compiler, but may be omitted in JSDoc.
+
+
+
+
+
+ Arrays and objects (type applications and record types)
+
+
+
+ An array of MyClass instances.
+
{Array.<MyClass>}
+// or:
+{MyClass[]}
+
+
+
+ An object with string keys and number values:
+
{Object.<string, number>}
+
+
+
+ An object called 'myObj' with properties 'a' (a number), 'b' (a string), and 'c' (any type).
+
+ JSDoc supports Closure Compiler's syntax for defining array and object types.
+
+
+ You can also indicate an array by appending [] to the type that is contained in the array. For example, the expression string[] indicates an array of strings.
+
+
+ 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.
+
+
+
+
+
+ Nullable type
+
+
+
+ A number or null.
+
{?number}
+
+
+
+
+
+ This indicates that the type is either the specified type, or null.
+
+
+
+
+
+ Non-nullable type
+
+
+
+ A number, but never null.
+
{!number}
+
+
+
+
+
+ Indicates that the value is of the specified type, but cannot be null.
+
+
+
+
+
+ Variable number of that type
+
+
+
+ This function accepts a variable number of numeric parameters.
+
@param {...number} num
+
+
+
+
+
+ Indicates that the function accepts a variable number of parameters, and specifies a type for the parameters. For example:
+
+
+
/**
+ * 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;
+}
+
+
+
+ An optional parameter foo with default value 1.
+
@param {number} [foo=1]
+
+
+
+
+
+ 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.
+
+ Document a callback using the @callback tag. The syntax is identical to the @typedef tag,
+ except that a callback's type is always
+ function.
+
+
+
+
+
+ Type definitions
+
+
+
+ Documenting a type with properties 'id', 'name', 'age'.
+
/**
+ * @typedef PropertiesHash
+ * @type {object}
+ * @property {string} id - an ID.
+ * @property {string} name - your name.
+ * @property {number} age - your age.
+ */
+
+/** @type {PropertiesHash} */
+var props;
+
+
+
+
+
+ You can document complex types using the @typedef tag, then refer to the type definition elsewhere in your documentation.
+
+
+
+
+
+
+
+
+
+
\ 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.
+
+
+
+
Type name
+
Syntax examples
+
Description
+
+
+
+
Symbol name (name expression)
+
+{% example %}
+
{boolean}
+{myNamespace.MyClass}
+
+{% endexample %}
+
+
+
+ Specifies the name of a symbol. If you have documented the symbol, JSDoc creates a link to the
+ documentation for that symbol.
+
+
+
+
+
+
+ Multiple types (type union)
+
+
+{% example "This can be a number or a boolean." %}
+
{(number|boolean)}
+
+{% endexample %}
+
+
+
+ This means a value can have one of several types, with the entire list of types enclosed in
+ parentheses and separated by |. The parentheses are suggested for Closure Compiler,
+ but may be omitted in JSDoc.
+
+
+
+
+
+
+ Arrays and objects (type applications and record types)
+
+
+{% example "An array of MyClass instances." %}
+
{Array.<MyClass>}
+// or:
+{MyClass[]}
+
+{% endexample %}
+
+{% example "An object with string keys and number values:" %}
+
{Object.<string, number>}
+
+{% endexample %}
+
+{% example "An object called 'myObj' with properties 'a' (a number), 'b' (a string), and 'c' (any type)." %}
+
+ JSDoc supports Closure Compiler's syntax for defining array and object types.
+
+
+ You can also indicate an array by appending [] to the type that is contained in the
+ array. For example, the expression string[] indicates an array of strings.
+
+
+ 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.
+
+
+
+
+
+
+ Nullable type
+
+
+{% example "A number or null." %}
+
{?number}
+
+{% endexample %}
+
+
+
+ This indicates that the type is either the specified type, or null.
+
+
+
+
+
+
+ Non-nullable type
+
+
+{% example "A number, but never null." %}
+
{!number}
+
+{% endexample %}
+
+
+
+ Indicates that the value is of the specified type, but cannot be null.
+
+
+
+
+
+
+ Variable number of that type
+
+
+{% example "This function accepts a variable number of numeric parameters." %}
+
@param {...number} num
+
+{% endexample %}
+
+
+
+ Indicates that the function accepts a variable number of parameters, and specifies a type for the
+ parameters. For example:
+
+{% example %}
+
/**
+ * 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;
+}
+
+{% endexample %}
+
+
+
+
+
+ Optional parameter
+
+
+{% example "An optional parameter named foo." %}
+
+{% endexample %}
+
+{% example "An optional parameter foo with default value 1." %}
+
@param {number} [foo=1]
+
+{% endexample %}
+
+
+
+ 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.
+
+ Document a callback using the @callback tag. The
+ syntax is identical to the @typedef tag, except that a callback's type is always
+ function.
+
+
+
+
+
+
+ Type definitions
+
+
+{% example "Documenting a type with properties 'id', 'name', 'age'." %}
+
/**
+ * @typedef PropertiesHash
+ * @type {object}
+ * @property {string} id - an ID.
+ * @property {string} name - your name.
+ * @property {number} age - your age.
+ */
+
+/** @type {PropertiesHash} */
+var props;
+
+{% endexample %}
+
+
+
+ You can document complex types using the @typedef tag, then refer
+ to the type definition elsewhere in your documentation.
+
+
+
+
+
+[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.
-
-
-
-
Type name
-
Syntax examples
-
Description
-
-
-
-
Symbol name (name expression)
-
-{% example %}
-
{boolean}
-{myNamespace.MyClass}
-
-{% endexample %}
-
-
-
- Specifies the name of a symbol. If you have documented the symbol, JSDoc creates a link to the
- documentation for that symbol.
-
-
-
-
-
-
- Multiple types (type union)
-
-
-{% example "This can be a number or a boolean." %}
-
{(number|boolean)}
-
-{% endexample %}
-
-
-
- This means a value can have one of several types, with the entire list of types enclosed in
- parentheses and separated by |.
-
-
-
-
-
-
- Arrays and objects (type applications and record types)
-
-
-{% example "An array of MyClass instances." %}
-
{Array.<MyClass>}
-// or:
-{MyClass[]}
-
-{% endexample %}
-
-{% example "An object with string keys and number values:" %}
-
{Object.<string, number>}
-
-{% endexample %}
-
-{% example "An object called 'myObj' with properties 'a' (a number), 'b' (a string) and 'c' (any type)." %}
-
- JSDoc supports Closure Compiler's syntax for defining array and object types.
-
-
- You can also indicate an array by appending [] to the type that is contained in the
- array. For example, the expression string[] indicates an array of strings.
-
-
- 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.
-
-
-
-
-
-
- Nullable type
-
-
-{% example "A number or null." %}
-
{?number}
-
-{% endexample %}
-
-
-
- This indicates that the type is either the specified type, or null.
-
-
-
-
-
-
- Non-nullable type
-
-
-{% example "A number, but never null." %}
-
{!number}
-
-{% endexample %}
-
-
-
- Indicates that the value is of the specified type, but cannot be null.
-
-
-
-
-
-
- Variable number of that type
-
-
-{% example "This function accepts a variable number of numeric parameters." %}
-
@param {...number} num
-
-{% endexample %}
-
-
-
- Indicates that the function accepts a variable number of parameters, and specifies a type for the
- parameters. For example:
-
-{% example %}
-
/**
- * 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;
-}
-
-{% endexample %}
-
-
-
-
-
- Optional parameter
-
-
-{% example "An optional parameter named foo." %}
-
-{% endexample %}
-
-{% example "An optional parameter foo with default value 1." %}
-
@param {number} [foo=1]
-
-{% endexample %}
-
-
-
- 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.
-
- Document a callback using the @callback tag. The syntax is
- identical to the @typedef tag, except that a callback's type is always "function."
-
-
-
-
-
-
- Type definitions
-
-
-{% example "Documenting a type with properties 'id', 'name', 'age'." %}
-
/**
- * @typedef PropertiesHash
- * @type {object}
- * @property {string} id - an ID.
- * @property {string} name - your name.
- * @property {number} age - your age.
- */
-
-/** @type {PropertiesHash} */
-var props;
-
-{% endexample %}
-
-
-
- You can document complex types using the @typedef tag, then refer
- to the type definition elsewhere in your documentation.
-
-
-
-
-
-[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 @@
Getting Started
A quick-start to documenting JavaScript with JSDoc.