False positive "Unexpected data in tag constructor" for JSDuck

In general, JSDuck content prefers descriptions as first part of a documentation block, followed by any tags and their values.

/**
 * Description of class Foo.
 *
 * @class Foo
 * @constructor
 * @param x
 */
function Foo( x ) {}

/**
 * Description of method bar.
 *
 * @param y
 */
function bar( y ) {}

However, when documenting the constructor of a class, this doesn't work. JSDuck seems to require the description be after the @constructor tag in that case.

/**
 * Description of class Foo.
 *
 * @class Foo
 * @constructor
 *
 * Additional description for the constructor method.
 *
 * @param x
 */
function Foo( x ) {}

Example: https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Title

Source code: mediawiki.Title.js#L11-L21

However, jsDoc currently interprets this as an error:

Unexpected data in tag constructor at ./resources/src/mediawiki/mediawiki.Title.js :
    16 |  * @constructor
------------^
    17 |  *
    18 |  * Note that in the constructor and #newFromText method, `namespace` is the *default* namespace
>> 1 code style errors found!

This makes sense in general, but is required for JSDuck.

When doing the reverse (description first), such as:


/**
 * Aa.
 *
 * @class Foo
 *
 * Bb.
 *
 * @constructor
 * @param x
 */
function Foo( x ) {}

Then the above is interpreted as a class with "Bb" as description, "Aa" is ignored, and the constructor has no description.

Currently worked around by adding // jscs:disable jsDoc in Wikimedia source code around the constructor definition

jscs-dev / jscs-jsdoc

False positive "Unexpected data in tag constructor" for JSDuck #190