[英]Using JsDoc3 for large apps, How to group modules into sections/categories/submodules
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.我决定使用
JsDoc3
和DocStrap
来记录所有模块。 Modules are defined via require.js and in some places they are nested up to 3 or 4 levels deep.模块是通过 require.js 定义的,并且在某些地方它们嵌套了 3 或 4 层深。
Until now I understand that JsDoc documentation is split into four main sections: Modules, Classes, Tutorials, Globals.直到现在我才明白 JsDoc 文档分为四个主要部分:模块、类、教程、全局。 Each section has a header dropdown menu and a sidebar each of them listing all of the modules in linear fashion, alphabetically.
每个部分都有一个标题下拉菜单和一个侧边栏,每个部分都以线性方式按字母顺序列出所有模块。
I was wondering if there are options to display/group modules and Classes somehow to reflect the project structure.我想知道是否有选项可以显示/分组模块和类以某种方式反映项目结构。 I saw a git repository that document all the classes with lots of slashes
module1/submodule1/class1
, but it feels really though to digest this type of navigation.我看到了一个 git 存储库,它用大量斜杠
module1/submodule1/class1
记录了所有类,但感觉确实可以消化这种类型的导航。 Not to mention that the layout was having trouble with long titles overflowing from the sidebar.更不用说布局因侧边栏溢出的长标题而出现问题。
Currently I have a project layout similar to the schema from bellow.目前我有一个类似于下面的架构的项目布局。 It's wide and deep and I expect it to grow further.
它又宽又深,我预计它会进一步增长。
/Editor
---/Services
------/UI
------...
---...
---editorApp.js
/Engine
---/Core
------/...
---/Entities
------/...
---/Graphics
------/...
---/...
...
engine.js
/Web
---/Services
------/UI
------...
---...
---webApp.js
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.您可以使用
@namespace
来记录对象字面量或不应构造的“静态类”,例如本机Math
类。
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
.不幸的是, 没有简单的方法可以将模块标记为 namespaces 的成员,所以我完全放弃了
@module
标签,只使用了@class
和@namespace
。 Another really annoying thing about modules is you have to prepend module:
in front of every mention of a module in JSDoc comments.关于模块的另一个真正令人讨厌的事情是你必须在
module:
前面加上module:
在 JSDoc 注释中每次提到模块之前。 Eg you must do @type {module:my_mod}
instead of just @type {my_mod}
.例如,您必须执行
@type {module:my_mod}
而不仅仅是@type {my_mod}
。
So the structure of your project would look like this:因此,您的项目结构如下所示:
Editor.js编辑器.js
/**
* description of Editor.
* @namespace Editor
*/
const Editor = {
Services: require('./Services.js'),
...
}
module.exports = Editor
Services.js服务.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) 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
I've just published a new version of better-docs template which supports @category
tag.我刚刚发布了一个新版本的
@category
-docs模板,它支持@category
标签。 Long story short you can add @category
tag to your class/module/whatever and it will be namespaced in the sidebar.长话短说,您可以将
@category
标签添加到您的类/模块/任何内容中,它将在侧边栏中被命名空间。
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.