How to document simple class within a self-invoking function?

Question

How to document following code fragment? When I leave it as it is Foo.bar has no description. When I add @memberof tag it will be documented as static property. Adding @instance tag changes nothing. This is rather simple and common code pattern, so it should be easy to document, am I right? I hate jsdoc...

/**
 * @namespace
 */
var ns;

(function (ns) {
    'use strict';

    /**
     * Constructs class
     * @class ns.Foo
     */
    function Foo() {
    }

    /**
     * Blabla
     */
    Foo.prototype.bar = function () {

    };

    ns.Foo = Foo;

})(ns || (ns = {}));

score 3 · Accepted Answer · answered Oct 07 '14 at 16:20

3

Use @lends to tell jsdoc that what you have in the function belongs to your namespace. This way you don't have to pepper your code with @memberof everywhere. The following works when I run it here:

/**
 * @namespace
 */
var ns;

(/** @lends ns */ function (ns) {
    'use strict';

    /**
     * Constructs class
     * @class
     */
    function Foo() {
    }

    /**
     * Blabla
     */
    Foo.prototype.bar = function () {

    };

    ns.Foo = Foo;

})(ns || (ns = {}));

answered Oct 07 '14 at 16:20

Louis

146,715
28
274
320

Now it works. I must have missed something earlier. However, in @JayKuri solution in generated documentation, the class is named ns.Foo, whereas in yours - ns~Foo. I'm not sure what's the difference. – jesper Oct 07 '14 at 17:43
1

I forgot this detail. In `ns.Foo` the symbol `Foo` is understood to be a static member, whereas in `ns~Foo` it is an inner member. (The doc is [here](http://usejsdoc.org/about-namepaths.html)). I would say that `ns.Foo` is better. However, there's no way to get `@lends` to produce this name. (I tried.) The issue has been reported so I'm hopeful that a new version will upgrade `@lends` to handle it properly. I prefer to live with the incorrect notation and trust that when the issue is fixed, the upgrade will be painless, rather than have to write `@memberof` everywhere in my huge codebase. – Louis Oct 07 '14 at 17:57
Could you share a link to the issue you have mentioned? I can't find it. – jesper Oct 07 '14 at 18:12
This [issue](https://github.com/jsdoc3/jsdoc/issues/342) covers the problem of how jsdoc has issues handling inner vs static. When hegemonic figures it out for AMD-style modules, it'll be figured out for `@lends` too. – Louis Oct 07 '14 at 18:18
Another downside of `@lends` is that all functions and variables hidden inside closure are documented as inner, even if I add `@private` tag. – jesper Oct 07 '14 at 18:47
See here: http://pastebin.com/Yur4xUfd function which should be private is documented as inner method of namespace. – jesper Oct 08 '14 at 15:38
2

If I add `@private` then it is private and does not show up in the doc. Make sure you don't have a configuration option that tells jsdoc to output private entities, like `-p` or `--private` on the command line or the equivalent in a config file. – Louis Oct 08 '14 at 15:44
Yep, grunt sets private to true by default. Thanks, again. – jesper Oct 08 '14 at 16:00

score 1 · Answer 2 · answered Oct 07 '14 at 16:10

1

I think what you need to do is add @function and @memberof in addition to @instance. This tells jsdoc what it is and where it fits:

/**
 * Blabla
 * @function bar
 * @memberof ns.Foo
 * @instance
 */
Foo.prototype.bar = function () {

};

I find jsdoc obtuse as well... hang in there. :-)

answered Oct 07 '14 at 16:10

JayKuri

839
5
10

Thanks, it works, although for me it is FUBAR. In all my projects guessing proper jsdoc tags takes more time than it should. Moreover jsdoc snippets should carries documentation, but right now it holds a ton of meaningless tags. As I sad: I hate it - is there any better way to documents JS doc? – jesper Oct 07 '14 at 16:20
Not sure. I found NaturalDocs (http://www.naturaldocs.org) to be more predictable but it is a bit limited in presentation and I don't think it's being actively maintained. jsduck (https://github.com/senchalabs/jsduck) looks interesting, but I've not played with it really. My problem is that javascript modules I've toyed many times with creating one that is specifically for javascript and better at figuring things out... but alas, I have other work to do. Let me know if you find something you like better. – JayKuri Oct 07 '14 at 16:29

How to document simple class within a self-invoking function?

2 Answers2