JSDoc: What is a relationship between modules and namespaces

Question

I faced a problem with understanding the purpose of namespaces and modules in a union. For example I have a class Game.utils.Matrix. I want to annotate Game as a namespace, utils as a module and Matrix as a class:

/**
 * @namespace Game
 */

/**
 * @module utils
 * @memberOf Game
 */

/**
 * Create a matrix
 * @constructor
 */
function Matrix(){}

It creates a documentation and the name path of the Matrix class is Game.utils~ Matrix, but if I follow the Module link its name path is Module: utils without the Game namespace prefix, and if I follow the Game link it does not contain the utils module link.

Moreover, I can't add another class to this module as This class is not shown in the utils module tab:

/**
 * Create Dictionary
 * @memberOf Game.utils
 * @constructor
 */
function Dictionary(){}

The question is: what is the correct way to document namespaces and modules and what is the use case for each of them?

Answer 1

I played with it a bit and I guess having modules in a namespaces is a bit tricky. What worked for me is to define a module utils and a namespace which references it. The module is called utils however, not Game.utils but in Game you can see a property which links to it.

/**
 * @namespace Game
 * @property {module:utils} utils
 */

/**
* @module utils
*/

/**
 * Create a matrix
 * @class
 */
function Matrix(){}