Using JsDoc3 for large apps, How to group modules into sections/categories/submodules

Question

I am working on an app which will become quite huge in time. I have decided to use JsDoc3 and DocStrap to document all modules. Modules are defined via

Answer 1

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

Answer 2

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.