cwilson1031 / jsdoc-toolkit

Automatically exported from code.google.com/p/jsdoc-toolkit
0 stars 0 forks source link

Cannot document class name with hyphen #318

Closed GoogleCodeExporter closed 8 years ago

GoogleCodeExporter commented 8 years ago
Actually the toolkit cannot support class name containing hyphen :

CLASS['my-Class'] = CLASS.Base.extends ({...})

Original issue reported on code.google.com by jeremypa...@gmail.com on 17 Mar 2011 at 11:34

GoogleCodeExporter commented 8 years ago
The problem see to be with the '' markers.
It also don't document symbols with ''(or "").
eg.:
var foo = {
  'bar': 0
};
For this example the work around is simple. What if the property name needs the 
'' like:
var foo = {
  'some weird name': 0
};

Original comment by prusse.m...@gmail.com on 18 Mar 2011 at 5:50

GoogleCodeExporter commented 8 years ago
Documenting symbols with names that must be quoted is not supported in JSDoc 
Toolkit, and would be extremely difficult to add support for--I'd have to do a 
total rewrite.

Oh yeh, I *did* do a total rewrite, and quoted names will be supported in JSDoc 
3. However I would strongly recommend you reconsider using them in your API 
because it makes writing documentation much more complicated. For example the 
following documentation gymnastics are required for even a simple example:

    /** @namespace window */

    var proto = {};

    /**
        @alias "Some weird name."
        @memberof window["my-class"]#
        @namespace
     */
    proto["Some weird name."] = {
        /** Document me. */
        "bar": 0
    };

    /** @class */
    window["my-class"] = CLASS.create(proto);

That same example without quoted names is MUCH simpler:

    /** @class */
    var myClass = function() {};

    /** @namespace */
    myClass.prototype.nonweirdName = {
        /** Document me. */
        bar: 0
    }

Original comment by micmath on 19 Mar 2011 at 12:08