将JsDoc3用于大型应用程序,如何将模块分组为sections/categories/submodules

Question

我正在开发一款将会变得非常庞大的应用程序.我决定使用JsDoc3并DocStrap记录所有模块.模块通过require.js定义,在某些地方,它们最多嵌套3或4级.

直到现在我才明白JsDoc文档分为四个主要部分:模块,类,教程,全局.每个部分都有一个标题下拉菜单和一个侧边栏,每个标题按字母顺序列出liniar方式的所有模块.

我想知道是否有选项来显示/分组模块和类以某种方式反映项目结构.我看到了一个git存储库,它记录了所有带有大量斜线的类module1/submodule1/class1,但感觉真的是要挖掘这种类型的导航.更不用说布局在侧边栏溢出的长标题方面遇到了麻烦.

目前我的项目布局类似于下面的架构.它广泛而深入,我希望它能够进一步发展.

/Editor
---/Services
------/UI
------...
---...
---editorApp.js
/Engine
---/Core
------/...
---/Entities
------/...
---/Graphics
------/...
---/...
...
engine.js
/Web
---/Services
------/UI
------...
---...
---webApp.js

Answer 1

很好的问题。我也遇到了同样的问题。

我使用命名空间将类组合到一个包中。一个大项目可能有多个命名空间。一个非常大的项目可能有名称空间，其成员本身就是名称空间。

命名空间基本上是一组静态对象。您可以使用@namespace来记录不应构造的对象字面量或“静态类”，例如本机Math类。

不幸的是，没有简单的方法可以将模块标记为 namespaces 的成员，因此我@module完全放弃了标记，仅使用@class和@namespace。关于模块的另一个真正令人讨厌的事情是，您必须module:在 JSDoc 注释中每次提到模块之前添加前缀。例如，您必须执行@type {module:my_mod}而不仅仅是@type {my_mod}。

因此，您的项目结构如下所示：

编辑器.js

/**
 * description of Editor.
 * @namespace Editor
 */
 const Editor = {
   Services: require('./Services.js'),
   ...
 }
 module.exports = Editor

服务.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（假设 UI 是一个类）

/**
 * 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

我刚刚发布了一个支持标签的新版本的Better-docs模板@category。长话短说，您可以将@category标签添加到您的类/模块/任何内容，并将在侧边栏中命名。