Using JsDoc3 for large apps, How to group modules into sections/categories/submodules
Excellent question. I’ve run into the same problem too.
I use namespaces to group classes together into a single package. A big project could have multiple namespaces. A really big project could have namespaces whose members are themselves namespaces.
A namespace is basically a grouping of static objects. You can use @namespace
to document an object literal, or a “static class” that shouldn’t be constructed, for example, the native Math
class.
Unfortunately there is no easy way to label modules as members of namespaces, so I’ve abandoned the @module
tag altogether, using only @class
and @namespace
. Another really annoying thing about modules is you have to prepend module:
in front of every mention of a module in JSDoc comments. E.g. you must do @type {module:my_mod}
instead of just @type {my_mod}
.
So the structure of your project would look like this:
Editor.js
/**
* description of Editor.
* @namespace Editor
*/
const Editor = {
Services: require('./Services.js'),
...
}
module.exports = Editor
Services.js
/**
* description of Services.
* @namespace Editor.Services
* ^^^^^^^ shows it’s a member of Editor
*/
const Services = {
UI: require('./UI.js'),
...
}
module.exports = Services
UI.js (let’s say UI is a class)
/**
* description of UI.
* @memberof Editor.Services
* ^^^^^^^^^ need to tell JSDoc UI is a member
* @class
* ^^^^^^ optional, as JSDoc knows ES6 classes
*/
class UI {
constructor() {...}
}
module.exports = UI
I've just published a new version of better-docs template which supports @category
tag. Long story short you can add @category
tag to your class/module/whatever and it will be namespaced in the sidebar.