Get JSDoc to correctly document nested closures

时间:2016-08-31 17:34:56

标签: javascript jsdoc jsdoc3

I have a large, well-structured JavaScript object that is something like this:

/**
 * My 'class' begins here.  JSDoc barfs on this.
 */
var MyClass = (function(window, document, $) {

    return function(options) {

        "use strict";

        var
            x = 123,

            /**
             * This is a "public" function.
             */
            myFunc = function() { /*...*/ },

            /**
             * This is some other "private" function.
             */
            otherFunc = function() { /*...*/ };

        return {
            myFunc: myFunc
        };
    };

})(window, document, window.jQuery);

In effect, an outermost closure is used to control the global scope seen by an inner closure that implements a form of the module pattern: The inner function is effectively a constructor, and its nested functions are effectively methods, and the returned object is effectively a list of what parts of it are "public".

JSDoc hates this.

(For the record, I'm using JSDoc 3.4.)

I've tried several variants on @lend and @export and @namespace and @memberof in lots of places in this code, but no matter what I do, JSDoc refuses to notice any of the inner functions at all — it doesn't just "not associate them to the right things;" it doesn't include them at all in any of the output files.

This is an excellent pattern for tightly encapsulating classic JavaScript, not just encapsulating its internals but its dependencies too, and our real-world application uses this pattern in many many thousands of lines of code. So our JavaScript itself isn't going to change structure any time soon: Only the comments can reasonably be altered.

I'd like to be able to use JSDoc to document this application, but JSDoc fails badly on this no matter what I give it. Poking around on StackOverflow has identified ways to deal with various well-known module systems, but I haven't found solid answers for plain-jane JavaScript that uses multiply-nested closures.

So does anyone have a way to make JSDoc correctly generate MyClass as a "class-like" construct with the functions deeply nested inside it as "methods" of that "class"? I'm okay with having to tag otherFunc as @private or something to mark it as hidden, or having to tag myFunc as @public or something to mark it as visible, but no matter what I try, JSDoc doesn't seem to want to document any of those nested functions at all.

0 个答案:

没有答案