Allow @param and @return descriptions to be preceded by a newline.

This fixes two bugs that broke the @param and @return descriptions for
comments formatted like this (with a newline before the descriptions):

/**
Main description.

@method foo

@param {String} bar
    This is the bar param.

@param {String} baz
    This is the baz param.

@return {Boolean}
    Whether or not bar and baz got fooed.
**/

lib/docparser.js

@@ -260,7 +260,7 @@ YUI.add('docparser', function (Y) {
                 // extract the first word, this is the param name
                 match = REGEX_FIRSTWORD.exec(desc);
                 if (match) {
-                    name = trim(match[1]);
+                    name = trim(explodeString(match[1]));
                     desc = trim(match[2]);
                 }
 
@@ -383,7 +383,7 @@ YUI.add('docparser', function (Y) {
                 }
 
                 result = {
-                    description: explodeString(desc)
+                    description: Y.unindent(explodeString(desc))
                 };
 
                 if (type) {

tests/input/test/test.js

@@ -76,14 +76,33 @@
  * @returns something without a type
  */
 
+/**
+Test newlines before descriptions.
+
+@method testNewlineBeforeDescription
+
+@param {String} foo
+    This parameter is foo.
+
+@param {String} bar
+    This parameter is bar.
+
+    It does useful things.
+
+@return {Boolean}
+    Sometimes true, sometimes false.
+
+    Nobody knows!
+**/
+
     /**
      * Testing really long param description paring
      * @method reallyLongParamDesc
-     * @param {Object} config Object with configuration property name/value pairs. The object can be 
+     * @param {Object} config Object with configuration property name/value pairs. The object can be
      * used to provide default values for the objects published attributes.
      *
      * <p>
-     * The config object can also contain the following non-attribute properties, providing a convenient 
+     * The config object can also contain the following non-attribute properties, providing a convenient
      * way to configure events listeners and plugins for the instance, as part of the constructor call:
      * </p>
      *
@@ -187,17 +206,17 @@ This method has attr {{#crossLink "OtherClass2/optionalAttr:attr"}}{{/crossLink}
 */
 
 /**
-Test `\{{foobar\}}` `\{{barfoo\}}` 
+Test `\{{foobar\}}` `\{{barfoo\}}`
 @method hbHelper1
 */
 
 /**
-Test `\{{foobar2\}}` `\{{barfoo2\}}` 
+Test `\{{foobar2\}}` `\{{barfoo2\}}`
 @method hbHelper2
 */
 
 /**
-Test `\{{foobar3\}}` `\{{barfoo3\}}` 
+Test `\{{foobar3\}}` `\{{barfoo3\}}`
 @method hbHelper3
 */
 

tests/parser.js

@@ -294,6 +294,33 @@ suite.add(new YUITest.TestCase({
         Assert.isTrue(item2.params[0].multiple, 'Multiple not set');
         Assert.isUndefined(item2["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.');
+        Assert.areSame('foo', item.params[0].name, 'Param 0 should have the correct name.');
+        Assert.areSame('bar', item.params[1].name, 'Param 1 should have the correct name.');
+
+        Assert.areSame(
+            'This parameter is foo.',
+            item.params[0].description,
+            'Param 0 should have the correct description.'
+        );
+
+        Assert.areSame(
+            'This parameter is bar.\n\n    It does useful things.',
+            item.params[1].description,
+            'Param 1 should have the correct description.'
+        );
+    },
+    'test: indented return description': function () {
+        var item = this.findByName('testNewlineBeforeDescription', 'myclass');
+
+        Assert.areSame('Boolean', item.return.type, 'Type should be correct.');
+        Assert.areSame(
+            'Sometimes true, sometimes false.\nNobody knows!',
+            item.return.description,
+            'Description indentation should be normalized to the first line.'
+        );
     },
     'test: object parameters': function () {
         var item, props;