Drop a line

[mightyiam]

The issue with the following example is that the whole @param thing is rendered as one line.

JSDoc actually supports this and produces multiple lines.

/**
 * The constructor
 * @constructor
 * @param {Object} options
 *   * `this`: sets this
 *   * `that`: determines that
 * @api public
 */

How would you go about doing something like this, please?

[jonschlinkert]

This wouldn't be too difficult to implement. I'm on vacation until Thursday the 16th, but I can look at doing it when I get back. In the meantime you can use this format if you want:

/**
 * The constructor
 * @constructor
 * @param {Object} `options`
 *   @option `this` [options] sets this
 *   @option `that` [options] determines that
 * @api public
 */

Make sure you have the property names in backticks (e.g. options) and use the square brackets to specify the "parent" property. So [options] means that the property is a child of options. I did it that way so we didn't need to use formatting to indicate data relationships.

[mightyiam]

The @option example is good for what I require, exactly.

What about when I would like multiple paragraphs, is that possible?

/**
 * @param {String} `name` This is the name
 *   Specify this to name the thing
 *
 *   Naming the thing should be a pleasant experiance.
 */

Or something like that.

[jonschlinkert]

Sorry, was on vacation. The multiple paragraph thing is more complicated. I know this is heavy-handed, but I've intentionally avoided implementing multi-paragraph support b/c I think the goal should be to describe methods with examples and brief descriptions. Anything beyond that (again, IMHO) means that either the method is too complicated or I need to add docs beyond what is appropriate for code comments. (in other words, keep API docs brief and create user docs when more detail is needed).

I know that others might not agree with this so I'm not opposed to adding multi-paragraph support for params. I'll just need to think about the best way to do it. suggestions welcome

[jonschlinkert]

oh, btw it might be good to carry this conversation over to parse-comments, since that's where this logic would be implemented.

[jonschlinkert]

closing since this was resolved in v1.0 of parse-comments.

The comment in your example now parses to:

[ { type: 'BlockComment',
    value:
     '\nThe constructor\n@constructor\n@param {Object} options\n  * `this`: sets this\n  * `that`: determines that\n@api public',
    range: [ 1, 141 ],
    loc:
     { start: { line: 2, column: 0 }, end: { line: 9, column: 3 } },
    codeStart: null,
    raw:
     '*\n * The constructor\n * @constructor\n * @param {Object} options\n *   * `this`: sets this\n *   * `that`: determines that\n * @api public\n ',
    code:
     { context: {},
       value: '',
       range: [ 142, 142 ],
       loc:
        { start: { line: 10, column: 3 }, end: { line: 10, column: 3 } } },
    description: 'The constructor',
    footer: '',
    examples: [],
    tags:
     [ { title: 'constructor', name: '', description: '' },
       { title: 'param',
         name: 'options',
         description: '* `this`: sets this\n  * `that`: determines that',
         type: { type: 'NameExpression', name: 'Object' },
         inlineTags: [] },
       { title: 'api', name: 'public', description: '' } ],
    inlineTags: [] } ]