Duplicate items when using @name

[GoogleCodeExporter]

What steps will reproduce the problem?
1. Document module format code using the @name tag

What is the expected output? What do you see instead?

The method to appear using the name specified only, and not in addition to
the regular declaration.

In the example the documentation will output both:

MyObject.init()

AND

MyObject.obj.init()

What version of the product are you using? On what operating system?

2.0.0

Please provide any additional information below.

Here is sample code to test:

(function() {
    /** @namespace */
    MyObject = function()
    {
        /** @private */
        var obj = {};

        /**
         * Initialize the object instance
         * @function
         * @name init
         */
        obj.init = function()
        {
            return;
        };

        return obj;
    }();
})();

Original issue reported on code.google.com by dwightb....@gmail.com on 31 May 2008 at 7:29

[GoogleCodeExporter]

I can't tell exactly what you are trying to accomplish, the information you 
provided doesn't say, but looking at your 
example I'm going to assume you want to document MyObject and MyObject.init.

The problem you are having is to do with the -a option (which I also assume you 
are using). That option instructs 
JsDoc Toolkit to try to document all functions, even if there is no comment 
provided for them. That is why obj.init is 
being documented.

I think I can hear you saying: But I DID document that function, and I said 
it's @name was "init" -- I can see my 
comment right there next to it!

But it doesn't work that way. The @name tag tells JsDoc Toolkit to treat the 
comment separate from the surrounding 
code. The fact that you happened to put it near another similarly named 
function is coincidental, you've told JsDoc 
Toolkit to treat them as separate. This is explained here:
    http://www.jsdoctoolkit.org/wiki/?page=name

As for solutions you can either stop telling JsDoc Toolkit to document the 
uncommented "obj.init" by removing the -
a option from the command line, or, if you want to keep the -a option for all 
other functions, you can tell JsDoc 
Toolkit to ignore just the "obj.init" function, like so...

(function() {
    /** @namespace */
    MyObject = function()
    {
        /** @private */
        var obj = {};

        /**
         * Initialize the object instance
         * @function
         * @name MyObject.init
         */

        /** @ignore */
        obj.init = function()
        {
           return;
        };

        return obj;
    }();
})();

Original comment by micmath on 1 Jun 2008 at 10:07

• Changed state: Invalid

[GoogleCodeExporter]

By the way, there are better ways to do what I think you are trying to do. 
Here's one, but feel free to follow up 
if it doesn't do what you need:

(function() {
    /** @namespace */
    MyObject = function()
    {
        var obj = 
        /** @scope MyObject */
        {
            /**
             * Initialize the object instance
             */
            init: function()
            {
                return;
            };

        };

        return obj;
    }();
})();

Original comment by micmath on 1 Jun 2008 at 10:17

[GoogleCodeExporter]

Here's another:

(function() {
    MyObject = {
        /**
         * Initialize the object instance.
         * @constructs
         */
        init: function()
        {
            return;
        };

    };
})();

Original comment by micmath on 1 Jun 2008 at 10:21

[GoogleCodeExporter]

My apologies, I somehow missed that when looking at the documentation!

As for your other examples, the first example would work, the second would not. 
 The primary importance is to 
have both private and public scope methods/vars, but also provide a reference 
handle so private members can 
access public members, that is done through the use of "obj"

I'd certainly rather reformat instead of adding @ignores everywhere!

Original comment by dwightb....@gmail.com on 1 Jun 2008 at 5:12

[GoogleCodeExporter]

By the way, your question has become the basis for the first entry into our 
brand new "FAQ page," as it does 
come up fairly regularly. Thanks for the reminder that I need to document that 
more clearly:

http://code.google.com/p/jsdoc-toolkit/wiki/FAQ

Original comment by micmath on 1 Jun 2008 at 6:55

[GoogleCodeExporter]

Thanks micmath, I had tried the FAQ before posting the issue, so this is a good 
step.

In my tests I've noticed that jsDoc reports an "undocumented symbol" when var 
is used while encased within 

(function(){
})();

for example:

(function() {
   /** @class An example class */
   var MyClass = function()
   {
      /** @scope MyClass */
      return {
         /** describe example method here */
         example: function()
         {
            return;
         }
      };
   };
})();

Removing either the initial "var" or taking the code block out of the encasing 
function resolves the issue.

Any idea why that is?

Original comment by dwightb....@gmail.com on 2 Jun 2008 at 1:40

[GoogleCodeExporter]

With the var inside the enclosing function, the MyClass symbol has no namepath. 
Well, technically it does but it 
isn't "MyClass". It's actually "$anonymous-Myclass", but you can't use that as 
a valid namepath. The result is 
there is no way to refer to it; you've created a private inner function of an 
anonymous function.

However I don't think this pattern is, by itself, useful so there isn't any 
reason to use it. In order to be useful you 
will eventually have to touch the global namespace, and at that point you will 
have a namepath that can be used. 
Removing the "var" makes MyClass a member of the global namespace, and thus 
"MyClass" becomes a valid 
namepath.

Original comment by micmath on 2 Jun 2008 at 6:32