Documenting singleton and @export

[GoogleCodeExporter]

Hi,

I'm trying to document singleton: http://jsfiddle.net/kyGvM/
/** @namespace */
var namespace = {};

(function() {
    /** 
     * Constructor 
     * @class 
     * @exports Singleton as namespace.singleton
     * @singleton */
     var Singleton = function() {
        /** */ this.prop = 1 
        this.method = function(){}
     }; 

    namespace.singleton = new Singleton();

})();

It jsDoc output looks perfect when I move Singleton to global scope: 
http://jsfiddle.net/kyGvM/1/ or http://jsfiddle.net/kyGvM/2/

Is there any way to do so without moving constructor to global scope?

Regards,
Tomek

Original issue reported on code.google.com by tomalec...@gmail.com on 1 Sep 2011 at 1:46

[GoogleCodeExporter]

The problem is that there is no such symbol with the namepath of "Singleton" 
anywhere in your code. Which is to say, from the *top-level* of your program 
(the global scope) there is nothing named "Singleton".

There _is_ a constructor named "Singleton" but it is hidden inside an anonymous 
function. And the exports tag needs to have the full global namepath to 
"Singleton". In JSDoc Toolkit you could do this by adding @name tags in every 
comment where you wanted to document a name that was not the actual name:

/**
 * @namespace
 * @property {Singleton} singleton
 */
var namespace = {};

(function() {
    /** 
     * @class
     * @name Singleton
     */
     var Singleton = function() {
        /** @name Singleton#prop */
        this.prop = 1

        /** @name Singleton#method */
        this.method = function(){}
     }; 

    namespace.singleton = new Singleton();

})();

Original comment by micmath on 1 Sep 2011 at 9:47

[GoogleCodeExporter]

Thanks for reply.

The problem is that I don't want symbol Singleton to be visible in my code, but 
namespace.singleton, and I'd like to export local variable Singleton as global 
namespace.singleton, as Map in 
http://code.google.com/p/jsdoc-toolkit/wiki/TagExports
where Map does not have global namepath.

So:
/**
 * @namespace
 * @property {Singleton} singleton
 */
var namespace = {};

(function() {
    /** 
     * @class
     * @name Singleton
     * @exports Singleton as namespace.singleton
     */
     var Singleton = function() {
        /** @name Singleton#prop */
        this.prop = 1

        /** @name Singleton#method */
        this.method = function(){}
     }; 

    namespace.singleton = new Singleton();

})();
generates output that I need, but commenting each name manually does not look 
nice.
(TagExports example does not have to @name doThings method )

/**
 * @namespace
 */
var namespace = {};

(function() {
    /** 
     * @exports Singleton as namespace.singleton
     */
     var Singleton = 
     /** @constructor */
     namespace.singleton =  function() {
        /** */ this.prop = 1

        this.method = function(){}
     };
     Singleton.prototype.anotherMethod = function(){}; 

    namespace.singleton = new Singleton();

})();
will also produce nice output, but I don't want to make constructor global 
variable even for couple of lines ;).

Original comment by tomalec...@gmail.com on 1 Sep 2011 at 11:10

[GoogleCodeExporter]

The difference is that the TagExports wiki page example does not use `this`. 
You might see what I mean if you wrote the following...

{{{

/** @namespace */
var namespace = {};

(function() {
   /**
    * @exports this as namespace.singleton
    */
     var Singleton = function() {
        /** a property of namespace.singleton */
        this.prop = 1

        this.method = function(){}
     }; 

    /** @namespace */
    namespace.singleton = new Singleton();

})();

}}}

But that is unlikely to be useful to you since that will affect all references 
to "this" everywhere. I really don't see how you can do what you want without 
using the @name tag. Even if you think it does not look nice it is the 
recommended way to do it.

By the way, if you are interested in using JSDoc 3, you may find this sort of 
thing is a little easier. For example, in JSDoc 3 you could write this...

{{{

/** @namespace */
var namespace = {};

(function() {
    /** @this namespace.singleton */
    var Singleton = function() {
        /** Document me. */
        this.prop = 1 
        this.method = function(){}
     }; 

    /** @namespace */
    namespace.singleton = new Singleton();

})();

}}}

Original comment by micmath on 2 Sep 2011 at 10:28