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

Question

我正在开发一个应用程序，它会随着时间的推移变得非常庞大。我决定使用 JsDoc3 和 DocStrap 来记录所有模块。模块是通过 require.js 定义的，在某些地方它们最多嵌套 3 或 4 层。

到目前为止，我了解到 JsDoc 文档分为四个主要部分：模块、类、教程、全局。每个部分都有一个 header 下拉菜单和一个侧边栏，每个部分都以线性方式按字母顺序列出所有模块。

我想知道是否有 display/group 模块和类的选项以某种方式反映项目结构。我看到了一个 git 存储库，其中记录了所有类，其中有很多斜线 module1/submodule1/class1，但感觉确实要消化这种类型的导航。更不用说布局有问题，长标题从边栏溢出。

目前我有一个类似于下面的架构的项目布局。它又广又深，我希望它能进一步发展。

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

Answer 1

问得好。我也运行遇到了同样的问题。

我使用 命名空间 将 class 组合成一个包。一个大项目可能有多个命名空间。一个真正的大项目可以有名称空间，其成员本身就是名称空间。

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

不幸的是有，所以我完全放弃了 @module 标签，只使用 @class 和 @namespace。关于模块的另一个非常烦人的事情是你必须在 JSDoc 注释中每次提到模块之前添加 module:。例如。你必须做 @type {module:my_mod} 而不仅仅是 @type {my_mod}.

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

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（假设 UI 是 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

我刚刚发布了支持 @category 标签的 better-docs 模板的新版本。长话短说，您可以将 @category 标记添加到您的 class/module/whatever，它将在侧边栏中命名空间。

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

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

javascript

documentation

jsdoc

jsdoc3