From ae188e9aae24234b07241a730c4636a7f4acc613 Mon Sep 17 00:00:00 2001 From: Sam Thorogood Date: Tue, 15 Aug 2017 14:01:21 +0100 Subject: [PATCH 1/6] add about-types page based on tags-type content --- content/en/about-types.md | 260 +++++++++++++++++++++++++++++++++++++ content/en/tags-param.md | 8 +- content/en/tags-type.md | 267 +++----------------------------------- 3 files changed, 282 insertions(+), 253 deletions(-) create mode 100644 content/en/about-types.md diff --git a/content/en/about-types.md b/content/en/about-types.md new file mode 100644 index 00000000..4752da94 --- /dev/null +++ b/content/en/about-types.md @@ -0,0 +1,260 @@ +--- +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 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 nameSyntax examplesDescription
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)." %} +
{{a: number, b: string, c}} myObj
+// or:
+{Object} myObj
+{number} myObj.a
+{string} myObj.b
+{*} myObj.c
+
+{% endexample %} +

+ 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." %} +
@param {number} [foo]
+// or:
+@param {number=} 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. +

+
+ Callbacks + +{% example %} +
/**
+ * @callback myCallback
+ * @param {number} x - ...
+ */
+
+/** @type {myCallback} */
+var cb;
+
+{% endexample %} + 		+

+ 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..c101cd68 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, or inline to indicate that a symbol is of a specific 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 nameSyntax examplesDescription
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)." %} -
{{a: number, b: string, c}} myObj
-// or:
-{Object} myObj
-{number} myObj.a
-{string} myObj.b
-{*} myObj.c
-
-{% endexample %} -

- 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." %} -
@param {number} [foo]
-// or:
-@param {number=} 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. -

-
- Callbacks - -{% example %} -
/**
- * @callback myCallback
- * @param {number} x - ...
- */
-
-/** @type {myCallback} */
-var cb;
-
-{% endexample %} - 		-

- 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,12 @@ var FOO = 1; var FOO = 1; ``` {% endexample %} + +To indicate that a variable is of a certain type, you can cast it with @type. 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 From 50523b08b94635aa371d9c7a6536a11df3eecc5a Mon Sep 17 00:00:00 2001 From: Sam Thorogood Date: Tue, 15 Aug 2017 14:03:51 +0100 Subject: [PATCH 2/6] fix *'s that Markdown is confused about --- content/en/about-types.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/content/en/about-types.md b/content/en/about-types.md index 4752da94..f08b9eb2 100644 --- a/content/en/about-types.md +++ b/content/en/about-types.md @@ -94,7 +94,7 @@ documented. {Object} myObj {number} myObj.a {string} myObj.b -{*} myObj.c +{*} myObj.c {% endexample %} @@ -163,10 +163,10 @@ documented. parameters. For example:

{% example %} -
/**
- * Returns the sum of all numbers passed to the function.
- * @param {...number} num A positive or negative number
- */
+
/**
+ * 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++) {
@@ -210,12 +210,12 @@ function sum(num) {
  
  
 {% example %}
-
/**
- * @callback myCallback
- * @param {number} x - ...
- */
+
/**
+ * @callback myCallback
+ * @param {number} x - ...
+ */
 
-/** @type {myCallback} */
+/** @type {myCallback} */
 var cb;
 

 {% endexample %}
@@ -234,15 +234,15 @@ var cb;
  
  
 {% 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.
- */
+
/**
+ * @typedef PropertiesHash
+ * @type {object}
+ * @property {string} id - an ID.
+ * @property {string} name - your name.
+ * @property {number} age - your age.
+ */
 
-/** @type {PropertiesHash} */
+/** @type {PropertiesHash} */
 var props;
 

 {% endexample %}

From e7978be769caf3979767b77afc9640e09bdfe1b9 Mon Sep 17 00:00:00 2001
From: Sam Thorogood 
Date: Tue, 15 Aug 2017 14:05:38 +0100
Subject: [PATCH 3/6] note about parens being optional

---
 content/en/about-types.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/content/en/about-types.md b/content/en/about-types.md
index f08b9eb2..03f00ec9 100644
--- a/content/en/about-types.md
+++ b/content/en/about-types.md
@@ -66,7 +66,8 @@ documented.
  
   

   This means a value can have one of several types, with the entire list of types enclosed in
-  parentheses and separated by |.
+  parentheses and separated by |. The parentheses are required for Closure Compiler,
+  but may be omitted in JSDoc.
   

  
 

From 27de4d2689278c2f312481ba7105d5405b9669b7 Mon Sep 17 00:00:00 2001
From: Sam Thorogood 
Date: Mon, 18 Sep 2017 12:44:07 +1000
Subject: [PATCH 4/6] review comments

---
 content/en/about-types.md | 18 +++++++++---------
 content/en/tags-type.md   |  7 ++++---
 2 files changed, 13 insertions(+), 12 deletions(-)

diff --git a/content/en/about-types.md b/content/en/about-types.md
index 03f00ec9..24320437 100644
--- a/content/en/about-types.md
+++ b/content/en/about-types.md
@@ -8,7 +8,7 @@ contain, a parameter type, or the type of a value returned by a function. These
 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.
+[param-tag]: tags-param.html
 
 ## Overview
 
@@ -17,8 +17,7 @@ built-in JavaScript type (for example, `string`); or a combination of these. You
 [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.
+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
@@ -66,7 +65,7 @@ documented.
  
   

   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 required for Closure Compiler,
+  parentheses and separated by |. The parentheses are suggested for Closure Compiler,
   but may be omitted in JSDoc.
   

  
@@ -89,7 +88,7 @@ documented.
 

 {% endexample %}
 
-{% example "An object called 'myObj' with properties 'a' (a number), 'b' (a string) and 'c' (any type)." %}
+{% example "An object called 'myObj' with properties 'a' (a number), 'b' (a string), and 'c' (any type)." %}
 
{{a: number, b: string, c}} myObj
 // or:
 {Object} myObj
@@ -108,8 +107,8 @@ documented.
   

   

   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.
+  documenting record types. As an alternative, you can document each property individually, which
+  enables you to provide more detailed information about each property.
   

  
 
@@ -223,8 +222,9 @@ var cb;
  
  
   

-  Document a callback using the @callback tag. The syntax is
-  identical to the @typedef tag, except that a callback's type is always "function."
+  Document a callback using the @callback tag. The
+  syntax is identical to the @typedef tag, except that a callback's type is always
+  function.
   

  
 
diff --git a/content/en/tags-type.md b/content/en/tags-type.md
index c101cd68..2c0de641 100644
--- a/content/en/tags-type.md
+++ b/content/en/tags-type.md
@@ -16,7 +16,7 @@ related:
 ## Overview
 
 The `@type` tag allows you to provide a type expression identifying the type of value that a symbol
-may contain, or inline to indicate that a symbol is of a specific type.
+may contain. For function parameters, you can also use an inline `@type` tag to identify its type.
 
 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
@@ -58,8 +58,9 @@ var FOO = 1;
 ```
 {% endexample %}
 
-To indicate that a variable is of a certain type, you can cast it with @type. The surrounding
-parentheses are required.
+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." }
 

From dfdfed4c7659204f9251fb6269e270ed71f56e63 Mon Sep 17 00:00:00 2001
From: Sam Thorogood 
Date: Mon, 18 Sep 2017 12:46:14 +1000
Subject: [PATCH 5/6] add About Types to TOC

---
 data/toc.json | 3 +++
 1 file changed, 3 insertions(+)

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"
         },

From 291afb3b6a5811500330816bd157f18706e84e18 Mon Sep 17 00:00:00 2001
From: Sam Thorogood 
Date: Mon, 18 Sep 2017 12:49:54 +1000
Subject: [PATCH 6/6] gulp run for change

---
 about-types.html | 276 +++++++++++++++++++++++++++++++++++++++++++++++
 index.html       |   5 +-
 tags-param.html  |  43 +++-----
 tags-type.html   | 254 +++----------------------------------------
 4 files changed, 308 insertions(+), 270 deletions(-)
 create mode 100644 about-types.html

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 @@
+
+
+
+
+
+  
+  
+  Use JSDoc: Types
+  
+  
+  
+  
+  
+
+
+
+  

+    @use JSDoc
+  

+  

+    
Types

+    
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 nameSyntax examplesDescription
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).

+            
{{a: number, b: string, c}} myObj
+// or:
+{Object} myObj
+{number} myObj.a
+{string} myObj.b
+{*} myObj.c
+

+          

+        		
+          

+            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;
+}
+

+          

+        

+          Optional parameter
+        
+          

+            
An optional parameter named foo.

+            
@param {number} [foo]
+// or:
+@param {number=} foo
+

+          

+          

+            
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.
+          

+        

+          Callbacks
+        
+          

+            
/**
+ * @callback myCallback
+ * @param {number} x - ...
+ */
+
+/** @type {myCallback} */
+var cb;
+

+          

+        		
+          

+            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/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.

       
Using namepaths with JSDoc 3

       
A guide to using namepaths with JSDoc 3.

+      
Types

+      
The JSDoc type system.

       
Command-line arguments to JSDoc

       
About command-line arguments to JSDoc.

       
Configuring JSDoc with a configuration file

@@ -217,8 +219,7 @@ 
Contribute

   
   

-    
+

     

       
Name and type
/**
  * @param {string} somebody
@@ -92,8 +91,7 @@ 
Names, types, and descriptions

 function sayHello(somebody) {
     alert('Hello ' + somebody);
 }
-

-    

+

     

       
Name, type, and description
/**
  * @param {string} somebody Somebody's name.
@@ -101,8 +99,7 @@ 
Names, types, and descriptions

 function sayHello(somebody) {
     alert('Hello ' + somebody);
 }
-

-    

+

You can add a hyphen before the description to make it more readable. Be sure to include a space before and after the hyphen.

Name, type, and description, with a hyphen before the description
/**
@@ -111,8 +108,7 @@ 
Names, types, and descriptions

 function sayHello(somebody) {
     alert('Hello ' + somebody);
 }
-
-
+

Parameters with properties

If a parameter is expected to have a specific property, you can document that property by providing an additional @param tag. For example, if an employee parameter is expected to have name and @@ -151,8 +147,7 @@

Parameters with properties

Project.prototype.assign = function(employees) { // ... }; - - +

Optional parameters and default values

The following examples show how to indicate that a parameter is optional and has a default value.

@@ -165,8 +160,7 @@

Optional parameters and default } alert('Hello ' + somebody); } - -

+
An optional parameter (using Google Closure Compiler syntax)
/**
  * @param {string=} somebody - Somebody's name.
@@ -177,8 +171,7 @@ 
Optional parameters and default
     }
     alert('Hello ' + somebody);
 }
-
-
+
An optional parameter and default value
/**
  * @param {string} [somebody=John Doe] - Somebody's name.
@@ -189,12 +182,11 @@ 
Optional parameters and default
     }
     alert('Hello ' + 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 for details about the type expressions that JSDoc supports.

+ types documentation for details about the type expressions that JSDoc supports.

Allows one type OR another type (type union)
/**
  * @param {(string|string[])} [somebody=John Doe] - Somebody's name, or an array of names.
@@ -207,8 +199,7 @@ 
Multiple types and repeatable
     }
     alert('Hello ' + somebody);
 }
-
-
+
Allows any type
/**
  * @param {*} somebody - Whatever you want.
@@ -216,8 +207,7 @@ 
Multiple types and repeatable
 function sayHello(somebody) {
     console.log('Hello ' + JSON.stringify(somebody));
 }
-
-
+
Allows a parameter to be repeated
/**
  * Returns the sum of all numbers passed to the function.
@@ -230,8 +220,7 @@ 
Multiple types and repeatable
     }
     return t;
 }
-
-
+

Callback functions

If a parameter accepts a callback function, you can use the @callback tag to define a callback type, then include the callback type in the @param tag.

@@ -251,8 +240,7 @@

Callback functions

function doSomethingAsynchronously(cb) { // code }; - - +

Syntax

-

@type {typeName} -

+

@type {typeName}

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.

-

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 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 nameSyntax examplesDescription
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 |. -

-
- 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).
- 
{{a: number, b: string, c}} myObj
-// or:
-{Object} myObj
-{number} myObj.a
-{string} myObj.b
-{} myObj.c
-
-
- 		-

- 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 - -
-
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;
-}
-
-
-
- Optional parameter - -
-
An optional parameter named foo.
- 
@param {number} [foo]
-// or:
-@param {number=} foo
-
-
-
-
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. -

-
- Callbacks - -
- 
/
-  @callback myCallback
-  @param {number} x - ...
- */
-
-/ @type {myCallback} /
-var cb;
-
-
- 		-

- 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. -

-
+

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.

+

The parameter type can be a built-in JavaScript type, such as number or Object, or a + JSDoc 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 for details.

Examples

Example
/** @type {(string|Array.)} */
 var foo;
 /** @type {number} */
 var bar = 1;
-
-
+

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.

Type expressions can accompany many tags.
/**
@@ -294,8 +65,12 @@ 
Examples

 
 /** @const {number} */
 var FOO = 1;
+
+

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." }

+ 
method(/** @type {Array<string>} */ (value));
-