我正在考虑为我的 Angular 应用程序添加文档，到目前为止，从我的发现来看，JSDoc 似乎是一个受欢迎的选择。
我现在正努力在一个结构中生成一些文档，该结构遵循模块和其中定义的相关控制器\指令\服务\等。
首先，这是我正在处理的应用程序中的代码示例：
angular.module('app', [
'app.core',
'app.features'
]);
(function() {
'use strict';
angular.module('app.features', [
'app.login',
'app.home',
'app.operations',
'app.management',
'app.customers'
]);
})();
(function() {
'use strict';
angular.module('app.customers', [
'app.layout'
]);
})();
(function() {
'use strict';
angular
.module('app.customers')
.controller('CustomersListController', Controller);
Controller.$inject = ['customerService', '$state'];
function Controller(customerService, $state) {
var vm = this,
searchText;
vm.customerService = customerService;
vm.fetchCollection = fetchCollection;
vm.deleteCustomer = deleteCustomer;
vm.goToEdit = goToEdit;
initialise();
function initialise() {
//some cool setup code here...
}
function fetchCollection(page, perPage){
//some logic here
}
function deleteCustomer(model) {
//delete logic
}
function goToEdit(model) {
$state.go('customer.edit', {customerId:model.id});
}
}
})();
所以现在我想写一些文档来涵盖CustomersListController中定义的功能。
我已经看到这篇文章，其接受的答案展示了一种定义关系的方法，所以我尝试在我的代码中使用它，如下所示：
/**
* @namespace app
*/
angular.module('app', [
'app.core',
'app.features'
]);
/**
* @class app.features
* @memberOf app
*/
(function() {
'use strict';
angular.module('app.features', [
'app.login',
'app.home',
'app.operations',
'app.management',
'app.customers'
]);
})();
/**
* @class app.customers
* @memberOf app.features
*/
(function() {
'use strict';
angular.module('app.customers', [
'app.layout'
]);
})();
/**
* @class app.customers.CustomersListController
*/
(function() {
'use strict';
angular
.module('app.customers')
.controller('CustomersListController', Controller);
Controller.$inject = ['customerService', '$state'];
function Controller(customerService, $state) {
var vm = this,
searchText;
vm.customerService = customerService;
vm.fetchCollection = fetchCollection;
vm.deleteCustomer = deleteCustomer;
vm.goToEdit = goToEdit;
initialise();
function initialise() {
//some cool setup code here...
}
/**
* @name fetchCollection
* @function
* @param {Number} page
* @param {Number} perPage
* @memberOf app.customers.CustomersListController
* @description This is the Customers List controller
* @returns {Array} An array of customer records
*/
function fetchCollection(page, perPage){
//some logic here
}
function deleteCustomer(model) {
//delete logic
}
function goToEdit(model) {
$state.go('customer.edit', {customerId:model.id});
}
}
})();
我正在使用gulp-documentation并设置了如下任务：
gulp.task('build_docs', [], function () {
var documentation = require('gulp-documentation');
gulp.src(paths.angularAppFiles)
.pipe(documentation({ format: 'html' }))
.pipe(gulp.dest('./docs-html'))
});
运行时会产生以下输出
我希望在左侧导航中显示正确的层次结构方面更具可读性，因此 app 在顶层，其次是 app.features 在第二级，app.customers 在第三级以目录样式显示。
另外，我注意到输出中也列出了“模块”，但我不确定它是如何生成的。我有模块声明，然后在我上面共享的代码中的一个模块上有一个控制器声明，那么 JSDoc 是从哪里获取的呢？
使用 JSDoc 语法定义 Angular 应用程序中声明的模块与其关联类（控制器、服务、指令等）之间的关系的正确方法是什么，以便它们出现在令人愉快的嵌套视图中，以便在生成的输出中轻松导航？
编辑
我也遇到过 ngdocs 和 gulp -ngdocs插件，但它似乎不是一个非常活跃的 repo，许多问题仍然存在。任何人都可以对这个插件及其适用性提供任何意见吗？我已经下载并运行了似乎运行良好的示例grunt-docs版本，尽管单击父“rfx”模块无法加载页面（在浏览器控制台中看到 404）——老实说让我有点紧张！