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

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?

Did you try documenting `var obj = ...` via `/** @class */? That way you should be able to properly reference it to add properties or for the return value.. — SGD, May 04 '15 at 18:56
According to http://usejsdoc.org/tags-class.html , `@class` is a synonym of `@constructor`, which I'm already applying to the factory function. Replacing `@constructor` with `@class` and/or moving the comment block to the object have no effect on the generated documentation. The class already appears in the documentation as a class, the problem is that instance methods are appearing as static properties. — ShadSterling, May 05 '15 at 15:00
Yes, but you do not document `obj`. My suggesting was to document `obj` inside of the function via `@class` and then reference that inner class as the return value of the function.. — SGD, May 21 '15 at 06:28

score 2 · Answer 1 · answered Aug 02 '16 at 10:20

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

answered Aug 02 '16 at 10:20

Hyddan

1,297
15
24

score 0 · Answer 2 · answered May 06 '15 at 14:12

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}).

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

2 Answers2