jsdoc：如何获取实例方法参数？

Question

I'm trying to document some old code with JSDoc3, and I'm stuck trying to get it to include in the documentation the parameters to instance methods - or to show anything as an instance property at all. I suspect the problem is that the code does not follow the expected idiom for faking classes in javascript, but I want to get everything documented before I start rewriting anything. I've tried to make a small example of the problem, with the structure of the actual code:

/**
 * Global function
 * @param  {Object} v Stuff that they're trying to avoid making global
 * @return {Object}   Updated v
 */
jsdoc_test = function( v ) {
    /**
     * Some stuff is defined in this namespace
     * @namespace space
     */
    var space = {};
    /**
     * Something that acts like a class
     * @name space.someclass
     * @memberOf space
     * @constructor
     * @type {function}
     * @param  {any}    y blah blah
     * @return {Object}   The constructed object
     */
    space.someclass = function( w ) {
        var obj = {
            source:  w,        // might need this again
            derived: foo( w ), // what we usually need
            etc:     "etc"     // and so on
        };
        /**
         * This should be a member function, but it appears as a static property
         * @name space.someclass.methodA
         * @memberOf space.someclass
         * @type {function}
         * @instance
         * @param  {any}    x Parameters do not appear in documentation
         * @return {Object}   this
         */
        obj.methodA = function( x ) {
            bar( x ); // or whatever methodA does
            return this;
        }
        /**
         * This should be a member function, but it doesn't show up at all
         * @name space.someclass.methodB
         * @memberOf space.someclass#
         * @type {function}
         * @param  {any}    y Parameters do not appear in documentation
         * @return {Object}   this
         */
        obj.methodB = function( y ) {
            baz( y ); // or whatever methodB does
            return this;
        }
        return obj;
        /**
         * This should be a member function, but it doesn't show up at all
         * @name space.someclass.methodC
         * @memberOf space.someclass.prototype
         * @type {function}
         * @param  {any}    z Parameters do not appear in documentation
         * @return {Object}   this
         */
        obj.methodC = function( z ) {
            qux( z ); // or whatever methodC does
            return this;
        }
        return obj;
    }
    // ...
}

I want all three methods to appear in the generated documentation as instance methods. As it is, methodA appears as a static property, while methodB and methodC (which follow suggestions from here ) do not appear at all

How do I get JSDoc3 to document instance methods, with their parameters, without rewriting the code?

Answer 1

Looks like you're using too many tags on your code. When you use @constructor , you shouldn't need @name or @type , since those are covered by using constructor.

So, you've got two options, I think.

Use @constructor and remove the redundant (conflicting) tags:

/**
 * Something that acts like a class
 * @constructor space.someclass
 * @memberOf space
 * @param  {any}    y blah blah
 * @return {Object}   The constructed object
 */

Or, if you don't want to use the @constructor tag, add the appropriate hinting yourself:

/**
 * Something that acts like a class
 * @name space.someclass
 * @memberOf space
 * @kind class
 * @param  {any}    y blah blah
 * @return {Object}   The constructed object
 */

In both cases, @type is redundant since you're documenting a class; the type would technically be the full name of your function (ie, @type {space.someclass} ).

Answer 2

A combination of @instance, @memberOf & @method should do it:

/**
 * This should now be a member function.
 * @instance
 * @memberOf space.someclass
 * @method methodA
 * @param {*} x Some parameter of any type.
 * @return {Object} this.
 */