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类。

不幸的是有no easy way to label modules as members of namespaces，因此我完全放弃了@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是一个类）

/**
 * 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标记添加到您的类/模块/任何内容，它将在边栏中命名空间。

将JsDoc3用于大型应用程序，如何将模块分组为部分/类别/子模块

2 个答案: