How to document modules and namespaces

[dcaillibaud]

Hi,

I'm not able to generate html doc from my code and didn't found
documentation about usins jsdoc in the case of module and namespace.

Here is a sample code, with a basic namespace, I tried a lot of @name
& @namespace tags without success, where's my mistake (with this
sample code, output is a quite blank page, with just "Namespace
myNamespace" but without any method).



/**
* @fileOverview Some file description
*/

if (!myNamespace) {
/** @namespace */
myNamespace = {};
}

(function(ns){

/** @module myNamespace.myFirstModule */
ns.myFirstModule = {}

/** @alias myNamespace.myFirstModule */
var M = ns.myFirstModule;

/**
* Here is the funcOne short description
*
* And here is a much longer one with a lot of words and verbosity
and so on, with a lot of
* words and verbosity and so on, with a lot of words and verbosity
and so on, with a lot
* of words and verbosity and so on, with a lot of words and
verbosity and so on, with a
* lot of words and verbosity and so on, with a lot of words and
verbosity and so on.
*
* @param {object} firstArg My first arg representing bla bla
* @param {function} callback The callback fct
* @param {object} [callbackArgs] Arguments for the callback fct,
not mandatory
* @name myNamespace.myFirstModule.funcOne
*/
M.funcOne = function(firstArg, callback, callbackArgs) {
var private1;
/**
* A little helper
* @param {Array} args The arguments in one array
* @inner
*/
function privFunc(args) {
// some code
}

privFunc(firstArg);
// do something
callback(callbackArgs);
}

})(myNamespace)

[Michael Mathews]

A "module," as JSDoc understands it, is defined in the CommonJS Modules standard. This says that a module identifier is a String of "terms" delimited by forward slashes, and that a global "require" function accepts that module identifier. These identifiers are often related to the filepath of the file containing the module source.

The code you've written does not reflect this understanding of what a module is. In JSDoc terms, it would be more accurate to call "ns.myFirstModule" a (nested) namespace. In short, the default template for JSDoc will not display modules as members of any other object, they must be global and must be identified by a string.

More info on using JSDoc with modules: http://usejsdoc.org/howto-commonjs-modules.html

Michael Mathews
mic...@gmail.com

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

[Daniel Caillibaud]

(sorry for delay, I just see this post never arrived because of wrong sender)

Thanks for such a detailed reply.

Le 11/06/12 à 23:21, Michael Mathews <mic...@gmail.com> a écrit :
MM> A "module," as JSDoc understands it, is defined in the CommonJS Modules standard. This says
MM> that a module identifier is a String of "terms" delimited by forward slashes, and that a
MM> global "require" function accepts that module identifier. These identifiers are often
MM> related to the filepath of the file containing the module source.
MM>
MM> The code you've written does not reflect this understanding of what a module is. In JSDoc
MM> terms, it would be more accurate to call "ns.myFirstModule" a (nested) namespace. In short,
MM> the default template for JSDoc will not display modules as members of any other object,
MM> they must be global and must be identified by a string.

It's right, I shouldn't use the "module" term because this sample code isn't reflecting a
module as CommonJS Modules standard defined it (it's the same with our real code).

So, is there any solution to see this code (it's perhaps not the best way coding js but it's the
code we have) documented with jsdoc ?

I can change the doc tags but I don't want to change deeply the code (of course I can change
"M.funcOne = function()" by "function funcOne(); M.funcOne = funcOne;", but it's not enough te
see this code documented).

Thanks a lot

--
Daniel

L'équipe de France de football est très appréciée : toutes les autres équipes
veulent la rencontrer.