对AngularJS应用程序使用JSDoc

Question

I am looking into adding documentation for my angular application and JSDoc seems to be a popular choice from my findings so far.

I am now struggling to get some documentation to generate in a structure that follows the modules and the associated controllers\\directives\\services\\etc that are defined within.

First here is a sample of the sort of code I have in the application I am working on:

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});
    }

  }
})();

So now I want to write some documentation to cover the functions defined in the CustomersListController.

I have seen this post with the accepted answer demonstrating a way to define the relationships so I have attempted to use this in my code like so:

/**
 * @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});
    }

  }
})();

I am using gulp-documentation and have a task set up like so:

gulp.task('build_docs', [], function () {
  var documentation = require('gulp-documentation');
  gulp.src(paths.angularAppFiles)
    .pipe(documentation({ format: 'html' }))
    .pipe(gulp.dest('./docs-html'))
});

Which when is run, produces the following output

I was hoping for something more readable in terms of showing the correct hierarchy in the nav on the left, so app at top level, followed by app.features in second level and app.customers at third in a directory style display.

Also, I notice 'module' is listed in the output too, but I'm not sure how that has been generated. I have module declarations and then a controller declaration on one of my modules in the code I have shared above, so where is JSDoc picking this up from?

What is the correct way using JSDoc syntax to define the relationships between modules declared in an angular application and their associated classes (controllers, services, directives, etc) so they appear in a pleasant nested view for easy navigation in the generated output?

EDIT

I have also come across ngdocs and the gulp-ngdocs plugin but it seems to not be a very active repo with a number of issues still open. Can anyone offer any comments on this plugin and it suitability? I have downloaded and run the sample grunt-docs version which seems to work well enough, although clicking on the parent 'rfx' module fails to load a page (seeing 404's in browser console) - makes me a little nervous to be honest!

Answer 1

The syntax for calling the gulp task has changed slightly since this post.

Latest syntax is below.

gulp.task('docs', function() {
var documentation = require('gulp-documentation');
gulp.src(tscConfig.compilerOptions.outDir)
    .pipe(documentation('html'))
    .pipe(gulp.dest('./docs-html'))
});