Document a singleton returned by an AMD module

[frontend_dev]

Hi, I really need some help with documenting a Singleton class, using requireJS.

My Code looks like this:

define(function () {

   var C = function () {  // constructor }

    C.prototype = {

         someStaticVar: "value",
        
         someMethod: function () { … }

    }

    return new C();

}

So what I want is to document this module as if it was returning an object literal, even if that is _actually_ a single instance of a "class". I also do not want an additional "class" entry to appear anywhere else. Plus, I have another module which also outputs a singleton like above, but also inherits from Module "C". I have tried various combinations, none gave me the output I expected and it seems like I am completely stuck. The best result I had was to document it like a class, but then my docs read "new require(...)". Of course very misleading since you shouldn't create a new instance in this case. Therefore, any help is appreciated!

[frontend_dev]

To answer my own question:

At least the first part was easier than I thought:

define(function () {

   /**
     * @exports C
     */

   var C = function () {  // constructor }

    C.prototype = /** @lends module:C */ {

         someStaticVar: "value",
        
         someMethod: function () { … }

    }

    return new C();

}

Now the docs look like I want them to, so that the module "C" appears as a single instance (not to be invoked with "new").

But now, if I have a similar module "D" that should inherit from "C", this does not work.

I write "D" like "C":

define(function () {

   /**
     * @exports D
     * extends module:C
     */

   var D = function () {  // constructor }

    D.prototype = /** @lends module:D */ {

         someOtherStaticVar: "value",
        
         someOtherMethod: function () { … }

    }

    return new D();

}

The methods and member from module "C" simply do not show. How would I do this then?

[Daniel Ellis]

I would suggest just making your singleton an object literal. If you're not going to be making multiple instances of the class, then a lot of the benefit of using its prototype is lost. Is D also a singleton? Just create a new object with C as D's prototype using Object.create:

var D = Object.create(C, {

    ...

    define additional properties here

    ...

};

return D;

--
You received this message because you are subscribed to the Google Groups "JSDoc Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jsdoc-users...@googlegroups.com.
To post to this group, send email to jsdoc...@googlegroups.com.
Visit this group at http://groups.google.com/group/jsdoc-users?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[frontend_dev]

I would suggest just making your singleton an object literal. If you're not going to be making multiple instances of the class, then a lot of the benefit of using its prototype is lost. Is D also a singleton? Just create a new object with C as D's prototype using Object.create:

Yes, that is something to think about, since both modules are in fact singletons. It is just that one module "inherits" from another, and I did this in a really basic and rather crude, but simple way (essentially ModuleC.prototype = new ModuleD(), with "hardwiring" some "Super" Methods). On the other hand I would have to introduce "Object.create" just for this specific case, and still: how would I document then that  ModuleD inherits from ModuleC, now as they are treated just like an object literal?