将JsDoc3用于大型应用程序,如何将模块分组为sections / categories / submodules [英] Using JsDoc3 for large apps, How to group modules into sections/categories/submodules
问题描述
我正在开发一款将会变得非常庞大的应用程序。我决定使用 JsDoc3
和 DocStrap
来记录所有模块。模块是通过require.js定义的,在某些地方它们最多嵌套3或4级。
I am working on an app wich will become quite huge in time. I have decided to use JsDoc3
and DocStrap
to document all modules. Modules are defined via require.js and in some places they are nested up to 3 or 4 levels deep.
直到现在我明白JsDoc文档分为四个主要部分:模块,类,教程,全局。每个部分都有一个标题下拉菜单和一个侧边栏,每个部分按字母顺序列出liniar方式的所有模块。
Untill now I understand that JsDoc documentation is split into four main sections: Modules, Classes, Tutorials, Globals. Each section has a header dropdown menu and a sidebar each of them listing all of the modules in liniar fashion, alphabetically.
我想知道是否有显示/组的选项模块和类以某种方式反映项目结构。我看到了一个git存储库,它记录了所有带有大量斜杠的类 module1 / submodule1 / class1
,但是我觉得这种导航很有用。更不用说布局在边栏上溢出长标题时遇到了麻烦。
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 diggest this type of navigation. 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.
命名空间基本上是一组静态对象。您可以使用 @namespace
来记录对象文字或不应构造的静态类,例如,本机 Math
class。
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.
不幸的是有没有简单的方法将模块标记为命名空间的成员,所以我完全放弃了 @module
标签,仅使用 @class
和 @namespace
。关于模块的另一个非常烦人的事情是你必须在JSDoc注释中每次提到模块前加上模块:
。例如。你必须 @type {module:my_mod}
而不只是 @type {my_mod}
。
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 (假设UI是一个类)
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
这篇关于将JsDoc3用于大型应用程序,如何将模块分组为sections / categories / submodules的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!