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 ) {}
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
In general, JSDuck content prefers descriptions as first part of a documentation block, followed by any tags and their values.
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.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:
This makes sense in general, but is required for JSDuck.
When doing the reverse (description first), such as:
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