@constructs overrides @class

[GoogleCodeExporter]

When using the @class, @lends and @constructs pattern to describe classes, the 
data for the @class is actually taken from @constructs - which is wrong in my 
eyes.

In @class I have a description of my class, about what it is for and the 
@constructs is for telling the developer how to use the constructor of my 
class. Obviously (in the default jsdoc template) I need to add my tags to the 
@constructs doc-block (e.g. @extends), where the context is simply wrong. 
Descriptions around my @class block are completely ignored.

Can this behavior between @class and @constructs be separated into two 
different and independent blocks.

Original issue reported on code.google.com by unigossi on 19 Dec 2010 at 3:34

[GoogleCodeExporter]

[deleted comment]

[GoogleCodeExporter]

[deleted comment]

[GoogleCodeExporter]

Well a class without a constructor is at the moment not documentable. An 
Example:

/**
 * @class YOOHOO.utils.SuperDooperClass
 */
YOOHOO.utils = MyClassCreator("SuperDooperClass", /** @lends 
YOOHOO.utils.SuperDooperClass# */ {
    /**
     * Some method
     */
    someMethod : function () {...}
});

This is a valid construction, but if you let it run through jsdoc, the 
following error comes up:
>> WARNING: Trying to document someMethod as a member of undocumented symbol 
YOOHOO.util.SuperDooperClass

Original comment by unigossi on 19 Dec 2010 at 4:56

[GoogleCodeExporter]

The following works for me:

/**
 * @name YOOHOO
 * @namespace
 */

/**
 * @name YOOHOO.utils
 * @namespace
 */

/**
 * @name YOOHOO.utils.SuperDooperClass
 * @class
 */
YOOHOO.utils = MyClassCreator("SuperDooperClass", /** @lends 
YOOHOO.utils.SuperDooperClass# */ {
    /**
     * Some method
     */
    someMethod : function () {}
});

Original comment by micmath on 21 Dec 2010 at 9:40

• Changed state: MoreInfoRequired

[GoogleCodeExporter]

Hey Michael,

I did some further investigations. At first I need to mention that the 
namespace YOOHOO.utils is already declared by me, that was my mistake I 
apologize.

I'm currently working with the original jsdoc template and referring its output.

At first the @name and @class solution seems works for me too. I can give my 
classes a description and it gets summarized as Class summary and detail. Oh 
wait, I have on my class detail page a section for my class summary and 
details, the first o_O. Well I'm used to read javadoc and the summary appears 
on the class index and the details on the class detail page, second o_O. I 
assume it means constructor summary and details here and gets named wrong. When 
hovering the summary link it shows a #constructor target in the href and proves 
it.

So I used the @name and @class combination and wanted to add my constructor 
details. But wait - there is no chance to do it with that pattern now, third 
o_O. So, you have to use two different document patterns for the same construct 
but with and without constructor, fourth o_O. Really? fifth o_O.

Either way I have no chance to document a class AND a constructor.

Probably this is a way out, because people already used @constructor for 
classes (just an idea):
- If @class AND @constructor are present use them either way.
- Use @constructor to document constructor and override @class IF NOT PRESENT 
as it is used for now
This way if no @class is present, the values from @constructor are written into 
the @class structure and should therefore work backwardscompatible.

Sixth o_O: Why do I have to use @name AND @class? Can't @class extend @name and 
use it implecitely when it is needed?

Hope those infos help. Anyway let me know what you need.

Cheers
gossi

Original comment by unigossi on 27 Dec 2010 at 8:07

[GoogleCodeExporter]

IMO this conversation should appear on the user's mailing list. I am -- right 
this moment -- making decisions about this for my implementation of JSDoc 3. 
Would you please summarise this into a more succinct proposal and post it on 
the user list?

http://groups.google.com/group/jsdoc-2

Original comment by micmath on 29 Dec 2010 at 12:08

• Changed state: WontFix

[GoogleCodeExporter]

Yeps done. Discussion continues here: 
https://groups.google.com/group/jsdoc-2/browse_thread/thread/74507c08a76d5b5d

Original comment by unigossi on 13 Jan 2011 at 11:38