improve docs for param tag

Author: hegemonic

Jake/articles/tags-param

@@ -14,16 +14,35 @@
 <h3>Overview</h3>
 
 <p>
-The @param tag (or @arg or @argument) documents a parameter of a function.
+The @param tag (or @arg or @argument) documents a function parameter.
+</p>
+
+<p>
+The @param tag requires you to specify the name of the parameter you are documenting. You can also
+include the parameter's type, enclosed in curly brackets, and a description of the parameter.
+</p>
+
+<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">@type 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>
 
 <h3>Examples</h3>
 
 <p>
-The following examples show the basic usage of @param.
+The following examples show how to include names, types, and descriptions in a @param tag.
 </p>
 
-{{#example}}Basic usage of @param
+{{#example}}Name only
 /**
  * @param somebody
  */
@@ -32,7 +51,7 @@ function sayHello(somebody) {
 }
 {{/example}}
 
-{{#example}}Using a type with @param
+{{#example}}Name and type
 /**
  * @param {string} somebody
  */
@@ -42,22 +61,36 @@ function sayHello(somebody) {
 {{/example}}
 
 
-{{#example}}Using type and description with @param
+{{#example}}Name, type, and description
 /**
- * @param {string} somebody Name
+ * @param {string} somebody Somebody's name.
  */
 function sayHello(somebody) {
     alert('Hello ' + somebody);
 }
 {{/example}}
 
 <p>
-The following examples show how to indicate that a parameter can be optional and has a default value
+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>
 
-{{#example}}An optional parameter
+{{#example}}Name, type, and description, with a hyphen before the description
 /**
- * @param {string} [somebody] Name
+ * @param {string} somebody - Somebody's name.
+ */
+function sayHello(somebody) {
+    alert('Hello ' + somebody);
+}
+{{/example}}
+
+<p>
+The following examples show how to indicate that a parameter is optional and has a default value.
+</p>
+
+{{#example}}An optional parameter (using JSDoc syntax)
+/**
+ * @param {string} [somebody] - Somebody's name.
  */
 function sayHello(somebody) {
     if (!somebody) {
@@ -67,9 +100,22 @@ function sayHello(somebody) {
 }
 {{/example}}
 
-{{#example}}Optional parameter and default value
+{{#example}}An optional parameter (using Google Closure Compiler syntax)
 /**
- * @param {String} [somebody=John Doe] Name
+ * @param {string=} somebody - Somebody's name.
+ */
+function sayHello(somebody) {
+    if (!somebody) {
+        somebody = 'John Doe';
+    }
+    alert('Hello ' + somebody);
+}
+
+{{/example}}
+
+{{#example}}An optional parameter and default value
+/**
+ * @param {string} [somebody=John Doe] - Somebody's name.
  */
 function sayHello(somebody) {
     if (!somebody) {
@@ -80,13 +126,15 @@ function sayHello(somebody) {
 {{/example}}
 
 <p>
-A parameter could also have several types instead of just one. It can also be used multiple times.
-The following examples reflect these situations.
+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">@type documentation</a> for details about the type expressions that JSDoc
+supports.
 </p>
 
-{{#example}}Multiple types
+{{#example}}Allows one type OR another type (type union)
 /**
- * @param {String|Array} [somebody=John Doe] Name or array of names
+ * @param {(string|string[])} [somebody=John Doe] - Somebody's name, or an array of names.
  */
 function sayHello(somebody) {
     if (!somebody) {
@@ -98,42 +146,57 @@ function sayHello(somebody) {
 }
 {{/example}}
 
-{{#example}}Variable parameter
+{{#example}}Allows any type
+/**
+ * @param {*} somebody - Whatever you want.
+ */
+function sayHello(somebody) {
+    console.log('Hello ' + JSON.stringify(somebody));
+}
+{{/example}}
+
+{{#example}}Allows a parameter to be repeated
 /**
  * Returns the sum of all numbers passed to the function.
- * @param {...Number} num A positive or negative number
+ * @param {...number} num - A positive or negative number.
  */
 function sum(num) {
-    var i=0, n=arguments.length, t=0;
-    for (; i&lt;n; i++) {
+    var i = 0, n = arguments.length, t = 0;
+    for (; i &lt; n; i++) {
         t += arguments[i];
     }
     return t;
 }
 {{/example}}
 
-{{#example}}Parameters that are callbacks
-/**
- * Does something asynchronously, calling the callback on completion.
- * @param {requestCallback} cb - The callback that handles the response.
- */
-function doSomethingAsynchronously(cb) {
-    // code
-};
+<p>
+If a parameter accepts a callback function, you can use the <a href="tags-callback.html">@callback
+tag</a> to define a callback type, then include the callback type in the @param tag.
+</p>
 
+{{#example}}Parameters that accept a callback
 /**
- * This callback is displayed as a global member.
+ * This callback type is called `requestCallback` and is displayed as a global symbol.
+ *
  * @callback requestCallback
  * @param {number} responseCode
  * @param {string} responseMessage
  */
+
+/**
+ * Does something asynchronously and executes the callback on completion.
+ * @param {requestCallback} cb - The callback that handles the response.
+ */
+function doSomethingAsynchronously(cb) {
+    // code
+};
 {{/example}}
 
 <h3>See Also</h3>
 
 <ul>
+    <li><a href="tags-callback.html">@callback</a></li>
     <li><a href="tags-returns.html">@returns</a></li>
     <li><a href="tags-type.html">@type</a></li>
     <li><a href="tags-typedef.html">@typedef</a></li>
-    <li><a href="tags-callback.html">@callback</a></li>
 </ul>

tags-param.html

@@ -187,17 +187,36 @@ <h3>Synonyms</h3>
 <h3>Overview</h3>
 
 <p>
-The @param tag (or @arg or @argument) documents a parameter of a function.
+The @param tag (or @arg or @argument) documents a function parameter.
+</p>
+
+<p>
+The @param tag requires you to specify the name of the parameter you are documenting. You can also
+include the parameter's type, enclosed in curly brackets, and a description of the parameter.
+</p>
+
+<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">@type 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>
 
 <h3>Examples</h3>
 
 <p>
-The following examples show the basic usage of @param.
+The following examples show how to include names, types, and descriptions in a @param tag.
 </p>
 
 <dl class="example">
-<dt>Basic usage of @param</dt>
+<dt>Name only</dt>
 <dd>
 <pre class="prettyprint lang-js">
 /**
@@ -210,7 +229,7 @@ <h3>Examples</h3>
 </pre>
 </dd>
 </dl><dl class="example">
-<dt>Using a type with @param</dt>
+<dt>Name and type</dt>
 <dd>
 <pre class="prettyprint lang-js">
 /**
@@ -223,11 +242,29 @@ <h3>Examples</h3>
 </pre>
 </dd>
 </dl><dl class="example">
-<dt>Using type and description with @param</dt>
+<dt>Name, type, and description</dt>
+<dd>
+<pre class="prettyprint lang-js">
+/**
+ * @param {string} somebody Somebody's name.
+ */
+function sayHello(somebody) {
+    alert('Hello ' + somebody);
+}
+
+</pre>
+</dd>
+</dl><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>
+
+<dl class="example">
+<dt>Name, type, and description, with a hyphen before the description</dt>
 <dd>
 <pre class="prettyprint lang-js">
 /**
- * @param {string} somebody Name
+ * @param {string} somebody - Somebody's name.
  */
 function sayHello(somebody) {
     alert('Hello ' + somebody);
@@ -236,15 +273,15 @@ <h3>Examples</h3>
 </pre>
 </dd>
 </dl><p>
-The following examples show how to indicate that a parameter can be optional and has a default value
+The following examples show how to indicate that a parameter is optional and has a default value.
 </p>
 
 <dl class="example">
-<dt>An optional parameter</dt>
+<dt>An optional parameter (using JSDoc syntax)</dt>
 <dd>
 <pre class="prettyprint lang-js">
 /**
- * @param {string} [somebody] Name
+ * @param {string} [somebody] - Somebody's name.
  */
 function sayHello(somebody) {
     if (!somebody) {
@@ -256,11 +293,28 @@ <h3>Examples</h3>
 </pre>
 </dd>
 </dl><dl class="example">
-<dt>Optional parameter and default value</dt>
+<dt>An optional parameter (using Google Closure Compiler syntax)</dt>
 <dd>
 <pre class="prettyprint lang-js">
 /**
- * @param {String} [somebody=John Doe] Name
+ * @param {string=} somebody - Somebody's name.
+ */
+function sayHello(somebody) {
+    if (!somebody) {
+        somebody = 'John Doe';
+    }
+    alert('Hello ' + somebody);
+}
+
+
+</pre>
+</dd>
+</dl><dl class="example">
+<dt>An optional parameter and default value</dt>
+<dd>
+<pre class="prettyprint lang-js">
+/**
+ * @param {string} [somebody=John Doe] - Somebody's name.
  */
 function sayHello(somebody) {
     if (!somebody) {
@@ -272,16 +326,18 @@ <h3>Examples</h3>
 </pre>
 </dd>
 </dl><p>
-A parameter could also have several types instead of just one. It can also be used multiple times.
-The following examples reflect these situations.
+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">@type documentation</a> for details about the type expressions that JSDoc
+supports.
 </p>
 
 <dl class="example">
-<dt>Multiple types</dt>
+<dt>Allows one type OR another type (type union)</dt>
 <dd>
 <pre class="prettyprint lang-js">
 /**
- * @param {String|Array} [somebody=John Doe] Name or array of names
+ * @param {(string|string[])} [somebody=John Doe] - Somebody's name, or an array of names.
  */
 function sayHello(somebody) {
     if (!somebody) {
@@ -295,51 +351,70 @@ <h3>Examples</h3>
 </pre>
 </dd>
 </dl><dl class="example">
-<dt>Variable parameter</dt>
+<dt>Allows any type</dt>
+<dd>
+<pre class="prettyprint lang-js">
+/**
+ * @param {*} somebody - Whatever you want.
+ */
+function sayHello(somebody) {
+    console.log('Hello ' + JSON.stringify(somebody));
+}
+
+</pre>
+</dd>
+</dl><dl class="example">
+<dt>Allows a parameter to be repeated</dt>
 <dd>
 <pre class="prettyprint lang-js">
 /**
  * Returns the sum of all numbers passed to the function.
- * @param {...Number} num A positive or negative number
+ * @param {...number} num - A positive or negative number.
  */
 function sum(num) {
-    var i=0, n=arguments.length, t=0;
-    for (; i&lt;n; i++) {
+    var i = 0, n = arguments.length, t = 0;
+    for (; i &lt; n; i++) {
         t += arguments[i];
     }
     return t;
 }
 
 </pre>
 </dd>
-</dl><dl class="example">
-<dt>Parameters that are callbacks</dt>
+</dl><p>
+If a parameter accepts a callback function, you can use the <a href="tags-callback.html">@callback
+tag</a> to define a callback type, then include the callback type in the @param tag.
+</p>
+
+<dl class="example">
+<dt>Parameters that accept a callback</dt>
 <dd>
 <pre class="prettyprint lang-js">
 /**
- * Does something asynchronously, calling the callback on completion.
+ * This callback type is called `requestCallback` and is displayed as a global symbol.
+ *
+ * @callback requestCallback
+ * @param {number} responseCode
+ * @param {string} responseMessage
+ */
+
+/**
+ * Does something asynchronously and executes the callback on completion.
  * @param {requestCallback} cb - The callback that handles the response.
  */
 function doSomethingAsynchronously(cb) {
     // code
 };
 
-/**
- * This callback is displayed as a global member.
- * @callback requestCallback
- * @param {number} responseCode
- * @param {string} responseMessage
- */
-
 </pre>
 </dd>
 </dl><h3>See Also</h3>
 
 <ul>
+    <li><a href="tags-callback.html">@callback</a></li>
     <li><a href="tags-returns.html">@returns</a></li>
     <li><a href="tags-type.html">@type</a></li>
     <li><a href="tags-typedef.html">@typedef</a></li>
-    <li><a href="tags-callback.html">@callback</a></li>
 </ul>
 
     </article>