CODEWITHSUNDEEP
javascriptjsdocjsdoc3
ShadSterling
ShadSterling

Reputation: 1820

jsdoc: How do I get instance method parameters to appear?

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?

Upvotes: 1

Views: 2460

Answers (2)

Hyddan
Hyddan

Reputation: 1337

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.
 */

Upvotes: 2

Chris
Chris

Reputation: 10338

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 (i.e., @type {space.someclass}).

Upvotes: 0

Related Questions