Documenting complex JavaScript Objects with custom Inheritance System

问题

I'm currently trying to migrate an existing server-side JavaScript API from its existing manually copy-and paste Inheritance System to a better and more reliable system. The pure prototyping cannot be used because state (variables) of the objects must also be inherited and must not be overriden in parent Objects.

So i'm thinking about using a good solution from John Reisig described here: http://ejohn.org/blog/simple-javascript-inheritance/

which workrs great for my case.

The only challenge i'm facing now is that most of the documentation frameworks won't handle objects constructed like this (OR i just don't know how to tell them). So my question is, how can i document classes like this:

namespace.ClassA = Class.extend({
    name : "",

    init: function(name){
        this.name = name;
    }
});

namespace.ClassB = ClassA.extend({
    sayName : function(){
        console.log(this.name);
    }
});

I'm preferring JsDoc but i couldn't think of a way to document this kind of classes with JsDoc. I also tried NaturalDocs which would kind-of work but i don't really want all this extra python stuff to be in the build process.

I think the main problems i have are with namespaces

For example:

    /** @memberof namespace**/
    namespace.ClassB = ClassA.extend(
    /** @lends ClassB.prototype **/
    {
            /** @constructs **/
            init : function(){
            },

    sayName : function(){
        console.log(this.name);
    }
});

will not include or display ClassB within the namespace "namespace"

回答1:

See if the following works for you. Note that your code snippet is not valid JavaScript in and of itself because namespace is not defined anywhere. At any rate, jsdoc will process it. What I've had to do was to be more verbose than I would have otherwise been. A few notes:

You could put the doclet that defines ClassA in front of the line that has namespace.ClassA.
The @lends tag needs a full path: /** @lends namespace.ClassB.prototype */

Here's the code:

/**
 * @namespace namespace
 */

namespace.ClassA = Class.extend({
    name : "",

    /**
     * @constructor
     * @memberof namespace
     * @name ClassA
     * @param name Blah.
     */
    init: function(name){
        this.name = name;
    }
});

/**
 * @constructor
 * @memberof namespace
 * @name ClassB
 */
namespace.ClassB = ClassA.extend(/** @lends namespace.ClassB.prototype */ {
    /**
     * @method
     */
    sayName : function(){
        console.log(this.name);
    }
});

来源：https://stackoverflow.com/questions/22246014/documenting-complex-javascript-objects-with-custom-inheritance-system

标签

javascript

documentation

ecmascript-5

jsdoc

jsdoc3