senchalabs / jsduck

Simple JavaScript Duckumentation generator.
http://docs.sencha.com/
GNU General Public License v3.0
1.5k stars 238 forks source link

Allow @constructor to be after description #641

Closed Krinkle closed 8 years ago

Krinkle commented 8 years ago

See also https://github.com/jscs-dev/jscs-jsdoc/issues/190.

It should be possible (for consistency with classes, methods and properties) to have the @constructor tag after the description instead of before.

This is typically complicated because JavaScript developers often define the constructor in the same block as the class. And we obviously want to avoid ambiguity between the description of the class and that of the constructor.

Consider the following examples:

/**
 * Description 1A.
 *
 * @class mw.Foo
 * @constructor
 * @param y
 */
function Foo (y) {}
// ^ Works.

/**
 * Description 2A.
 *
 * @class mw.Foo
 *
 * Description 2B.
 *
 * @constructor
 * @param y
 */
function Foo (y) {}
// ^ Doesn't work.
// Uses B as class description, A is ignored, constructor has no description.

/**
 * Description 3A.
 *
 * @class mw.Foo
 */
/**
 * Description 3B.
 *
 * @constructor
 * @param y
 */
function Foo (y) {}
// ^ Doesn't work.
// @constructor implicitly creates a new "@class Foo" when not in the same block

Worked around for now by using separate blocks (per the issue in example 2), and by switching to @method constructor instead of @constructor.

Until just now I wasn't aware of @constructor being deprecated. If there is no intent to backport this from @method, feel free to close this. Just filing it for the record and for someone else to find perhaps.

nene commented 8 years ago

Yeah... that's something unlikely to be improved. With the perspective of ECMAScript 6, the need for @constructor tag would be even smaller.