Namespaces are broken

[jsdoc]

Namespaces are broken

[micmath]

It would be helpful to me if you could reduce your example to just the minimal code necessary to demonstrate the issue you are reporting.

The syntax for @namespace (and several other tags) has been changed in non-backwards compatible ways from version 2 to 3. (That's why it's a uptick in the major revision number to 3, and not just to 2.5.)

It is not a bug that the new syntax is @namespace [name]. So that is a "wontfix" issue.

Also there is no -a option in version 3. This is by design, so no need to report that. You are welcome to raise the question on the mailing list as a discussion though, if you want to discuss it.

The following simplified example should work in version 2 or 3.

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

/**
 * Asset functions intended to only be used internally by the factory
 * @namespace
 */
jv.Assets = {
    /**
     * Run to initialize batch features on tables
     */
    tableCheckboxes: function() {
    }
}

[ProLoser]

It was fairly minified. I'll tweak the namespace descriptions accordingly. What should I do if I'm using a closure instead of an object literal?

[micmath]

Ok, but you do get points for conciseness here.

Interestingly, the fact that your code ever worked in JSDoc 2 is a due to an unreported bug. For example, you could have written this and the generated docs would have been the same:

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

/** @namespace */
jv.Util = (function(){
    (1,{
        /**
         * Utility wrapper for $.ajax();
         * 
         * args.ajaxType is required, must be unique
         * @example jv.UTIL.ajax({ ajaxType: 'test', url: 'profile/mine' });
         * @param {Object} args (required)
         * @returns {$.Deferred()}
         */
        ajax: function(args) {
        }
    });

    return {ajax: false};
})();

Which is obviously not correct. I might even get around to fixing that bug someday, so don't depend on it to stay in version 2 either!

The recommended way of documenting your code in 2 and 3 is either by supplying @memberof tags for each member or by using a single @lends tag, like so:

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

/** @namespace */
jv.Util = (function(){
    return /** @lends jv.Util*/ {
        /**
         * Utility wrapper for $.ajax();
         * 
         * args.ajaxType is required, must be unique
         * @example jv.UTIL.ajax({ ajaxType: 'test', url: 'profile/mine' });
         * @param {Object} args (required)
         * @returns {$.Deferred()}
         */
        ajax: function(args) {
        }
    };
})();

Note that in version 3 you cannot set the return type of a function with @type, you must use @returns. Although I'm not adverse to porting the support for @type on methods up to 3. If you think it is needed create a ticket, it shouldn't be too hard to implement.

refer to version 2 docs: http://code.google.com/p/jsdoc-toolkit/wiki/TagLends

[ProLoser]

Okay I finally got this working, but is this like the improper approach? Or is there a chance we could make it handle putting the /** @Lends */ before the return? And I take it it's too costly to automatically detect this with returning an object-literal?

[micmath]

Not sure what you are referring to when you say "improper approach?"

As for supporting @lends before return, it turns out that the /** @lends ... */ { handler is a special case... and I suppose /** @lends ... */ return { could just be another special case... Let me give it a think and play around with it.

[ProLoser]

One more thing, I'm having trouble getting this to show up properly in my docs too. It's an additional layer deep and really is just another namespace, but I feel like I'm having to do too many explicit doc-tags rather than hooking into a good coding convention and implicit detection. Is my structure/organization wrong or poor? Or is it just that everyone's implementation can tend to be completely unique?

My existing implementation is as such, and it's not rendering the docs properly:

/**
 * @namespace
 */
jv.Network = (function(){
    return {
        // Model contains no html/css/page specific logic
        /**
         * @namespace jv.Network.Model
         */
        Model: {
        },
        // Controller handles setting up actions (pages) in each section. Code should be triggered on relevant page.
        /**
         * @namespace jv.Network.Ctrl
         */
        Ctrl: {
        },
        /**
         * View related bindings and events. Each method should handle 1 binding/event
         * @namespace jv.Network.View
         */
        View: {
            /**
             * @param jobId string
             */
            overlay: function(data, title) {
            }
        }
    };
}());

Another note: I have multiple namespaces that have the same name, but different parents. In the navigation however they just show up as multiple copies of 'View' or 'Model' or 'Ctrl'. Should the navigation be tweaked to show the parent items? Should I not @namespace higher levels?

[micmath]

This should now work in 1abe982

/** @namespace */
var foo = (function() {

    /** @lends foo */
    return {
        /** document me */
        bar: 1
    }

})();

[ProLoser]

What do I do for deeply nested stuff? By that I mean, can I make Model or View a separate class or namespace with it's own methods? What organization do I need to accomplish this?

var myClass = (function(){
     return {
          Model: {},
          View: {
               titleBlock: function() {

               }
          }
     };
})();

[micmath]

Hi Dean,

Depends how you want it to show up in the generated output. Here's one way to do it, which will break the output up into more detailed pages:

/** @class */
var myClass = (function(){
    /** @lends myClass */
    return {
         /** @namespace */
         View: {
              /** Document me. */
              titleBlock: function() {

              }
         }
    };
})();

On the other hand, if the nested members are simple (don't require full-blown separate pages) you can dump them all on a single page as "properties", like so:

/** @namespace
    @property {object} View - Describe me if you want.
    @property {function} View.titleBlock
*/
var myClass = (function(){
    return {
         View: {
              titleBlock: function() {

              }
         }
    };
})();

For general "how do I..." questions like this, the jsdoc-users mailing list is a good place to have the discussion where it will benefit many users.