Multi line jsdoc @param tag

[jifeon]

I have the following code:

/**
 * @param {string} name
 * @param {
 *      {
 *          status?: boolean|{error?: boolean, success?: boolean},
 *          hint?: boolean|{error?: boolean, success?: boolean}
 *      }
 *      |FormFieldStatusCondition
 * } [condition]
 * @returns {FormFieldStatus} this
 */
setCondition: function (name, condition) {
    if (!(condition instanceof FormFieldStatusCondition)) {
        condition = new FormFieldStatusCondition(condition);
    }

    this._conditions[name] = condition;
    return this;
}

And PhpStorm works with it perfectly. I have not found any mentions about multi line @param tag in jsdoc specification. When I check my code by jscs it says:

Invalid JSDoc @param at js/Abstract/FormFieldStatus.js :
   315 |        /**
   316 |         * @param {string} name
   317 |         * @param {
-------------------^
   318 |         *      {
   319 |         *          status?: boolean|{error?: boolean, success?: boolean},


1 code style error found.

Could add support for multiline @param tag?

[markelog]

Usually it's done like that see "Parameters With Properties", but i suppose we could support this too.

[qfox]

@markelog I've done #312 . It uses http://github.com/Constellation/doctrine and it can be used for it easily.
It doesn't support multiline values and doesn't know about [variable] (idk why, maybe it's a bug) but 2 regexps fixes it. For jsdoc in case

var jsdoc = (['/**', 'Some test', '@param {', '    {', '      status?: boolean|{error?: boolean, success?: boolean},', '      hint?: boolean', '    }', '    |Custom', '  } [condition] about', '@returns {Object} this'].join('\n * ')+'\n */');
jsdoc = jsdoc.replace(/\n\s\*\s([^@])/g, '$1').replace(/\[(\w+)\]/g, '$1'); // these
require('doctrine').parse(jsdocsimple, { unwrap: true });

result:

{ description: 'Some test',
  tags:
   [ { title: 'param',
       description: 'about',
       type: undefined, // here is something bad
       name: 'condition' },
     { title: 'returns',
       description: 'this',
       type: [Object] } ] }

@jifeon Can you provide some info about this jsdoc code style?
I thought this syntax is better just because it's used everywhere:

@param {
  {
    status: ?(boolean | {error: ?boolean, success: ?boolean}),
    hint: ?(boolean|{error: ?boolean, success: ?boolean})
  } | FormFieldStatusCondition
} [condition] info

It's also used by Closure Complier. This jsdoc block was easily parsed by doctrine after removing redundant line breaks.

[qfox]

I think we should support multiline params but not that syntax. Both resources (usejsdoc, google closure) declares {?type}, {!type} and {type=} syntax but not {prop?: value}. Name is always clean there.
At jsdoc-toolkit there is a little bit another version: @param {type} [name] info. But not name?. Links:

• https://developers.google.com/closure/compiler/docs/js-for-compiler#types
• http://usejsdoc.org/tags-type.html#jsdoc-types
• https://code.google.com/p/jsdoc-toolkit/wiki/TagParam

Idk but I think it should been widely used before integration. ;-)

[jifeon]

Oh, sorry, its my fault of cause. The names should be without any question marks.

[qfox]

@jifeon I was confused ;-) Btw I've found one more jsdoc style for properties:

/**
 * @param {Object} person comment
 *   - {String} title comment
 *   - {Number} [age] comment
 */

Need to check it too.

[mikesherov]

Closing this issue as this should now be tackled by the JSDoc plugin.