Add rest parameters syntax for multiple params

docs/syntax/index.mustache

@@ -656,8 +656,8 @@ ATTRS[RENDERED] = {
         <ul>
             <li>`[name]` &mdash; optional parameter</li>
             <li>`[name=foo]` &mdash; default value is foo</li>
-            <li>`name*` &mdash; placeholder for 1..n args</li>
-            <li>`[name]*` &mdash; placeholder for 0..n args</li>
+            <li>`...name` &mdash; placeholder for 1..n args</li>
+            <li>`[...name]` &mdash; placeholder for 0..n args</li>
         </ul>
 
         <p>As shown in the example, you can also nest `@param` tags. 

lib/docparser.js

@@ -212,7 +212,7 @@ YUI.add('docparser', function (Y) {
             //   "type": "string",
             //   "optional": true, // [surroundedbybrackets]
             //   "optdefault": "if specified, this is always string to avoid syntax errors @TODO",
-            //   "multiple": true // endswith*
+            //   "multiple": true // endswith* or ...startswith
             // }
             // ],
             // @param {type} name description    -or-
@@ -312,6 +312,14 @@ YUI.add('docparser', function (Y) {
                     }
                 }
 
+                // This should run after the check for optional parameters
+                // and before the check for child parameters
+                // because the signature for 0..n params is [...args]
+                if (name.substr(0, 3) === '...') {
+                    multiple = true;
+                    name = name.substr(3);
+                }
+
                 // parse object.prop, indicating a child property for object
                 if (name.indexOf('.') > -1) {
                     match = name.split('.');

tests/input/test/test.js

@@ -76,6 +76,22 @@
  * @returns something without a type
  */
 
+/**
+test alternative 1..n param with ...args
+
+@method testrestparam1n
+@param {String} ...multiple my desc
+@returns something without a type
+**/
+
+/**
+test alternative 0..n param with ...args
+
+@method testrestparam0n
+@param {String} [...multiple] my desc
+@returns something without a type
+**/
+
 /**
 Test newlines before descriptions.
 

tests/parser.js

@@ -260,7 +260,7 @@ suite.add(new YUITest.TestCase({
         Assert.areSame('String', item2["return"].type, 'Type should not be missing');
     },
     'test: parameter parsing': function () {
-        var item, item2;
+        var item, item2, item3, item4;
         item = this.findByName('testoptional', 'myclass');
         Assert.isArray(item.params, 'Params should be an array');
         Assert.areSame(5, item.params.length, 'Failed to parse all 5 parameters');
@@ -294,6 +294,20 @@ suite.add(new YUITest.TestCase({
         Assert.isTrue(item2.params[0].multiple, 'Multiple not set');
         Assert.isUndefined(item2["return"].type, 'Type should be missing');
 
+        item3 = this.findByName('testrestparam0n', 'myclass');
+        Assert.isArray(item3.params, 'Params should be an array');
+        Assert.areSame(1, item3.params.length, 'Failed to parse all 5 parameters');
+        Assert.isTrue(item3.params[0].optional, 'Optional not set');
+        Assert.isTrue(item3.params[0].multiple, 'Multiple not set');
+        Assert.isUndefined(item3['return'].type, 'Type should be missing');
+
+        item4 = this.findByName('testrestparam1n', 'myclass');
+        Assert.isArray(item4.params, 'Params should be an array');
+        Assert.areSame(1, item4.params.length, 'Failed to parse all 5 parameters');
+        Assert.isUndefined(item4.params[0].optional, 'Optional should not be set');
+        Assert.isTrue(item4.params[0].multiple, 'Multiple not set');
+        Assert.isUndefined(item4['return'].type, 'Type should be missing');
+
         item = this.findByName('testNewlineBeforeDescription', 'myclass');
         Assert.isArray(item.params, 'Params should be an array.');
         Assert.areSame(2, item.params.length, 'Should parse two params.');
@@ -315,10 +329,10 @@ suite.add(new YUITest.TestCase({
     'test: indented return description': function () {
         var item = this.findByName('testNewlineBeforeDescription', 'myclass');
 
-        Assert.areSame('Boolean', item.return.type, 'Type should be correct.');
+        Assert.areSame('Boolean', item['return'].type, 'Type should be correct.');
         Assert.areSame(
             'Sometimes true, sometimes false.\nNobody knows!',
-            item.return.description,
+            item['return'].description,
             'Description indentation should be normalized to the first line.'
         );
     },