JSDoc with AngularJS

Question 1

I have encountered this issue as well. I am now writing documentation for angularjs codes through jsdoc comments like this:

1.Make a blank .js file with the following comment:

 /**
  * @namespace angular_module
  */

This will create a separate html in the generated documentation for listing all modules.

2.In javascript files that defines any new angular module, use this kind of comment

 /**
  * @class angular_module.MyModule
  * @memberOf angular_module    
  */

This will add an item in the above listing of all angular_modules, as well as creating a separate html page for MyModule, because it is a class.

3.For each angularjs service, use the following comment:

 /**
  * @function myService
  * @memberOf angular_module.MyModule
  * @description This is an angularjs service.
  */

This will add an item in the MyModule page for the service. Because it is added as a function, you can write documentation for input parameters using '@param' and return values using '@return'.

4.If I have quite long codes in a controller or directive of MyModule and want to have a separate html file to document it, I will annotate the controller or directive as a class using full path. e.g.

 /**
  * @class angular_module.MyModule.MyController
  */

In this way, MyController will be listed as one item in MyModule's documentation page.

Then, we can annotate codes within the controller as member functions of MyController.

 /**
  * @name $scope.aScopeFunction
  * @function
  * @memberOf angular_module.MyModule.MyController
  * @description
  */

In this way, this function's documentation will appear in the html file of MyController's html page. The dot-separated full path string builds the connection.

There are three types of syntaxes for namepath:

Person#say // the instance method named "say."
Person.say // the static method named "say."
Person~say // the inner method named "say."

However, one imperfect point of commenting controller as a class is that a "new" will be found before the controller name in the generated html documentation because it is described as class constructor.

Furthermore, you can define namespaces in order to add a hierarchical structure. For example, you can define a namespace to include all controllers
```
/**
 * @namespace MyApp.Controllers
 */
```

, and prefix all controller with MyApp.Controllers. You can also define namespaces like MyApp.Product or MyApp.Customer etc.

Although not perfect, I like using jsdoc to document angularjs codes because

It is simple;
The module-controller-function hierarchy are kept;
And it keeps jsdoc's merit that it is a browsable documentation site.

A table style jsdoc stylesheet:

Particularly, I've adapted the default jsdoc stylesheet to a table style like the Java API documentation. It looks clearer.

In Windows, I replace this file: C:\Users\user1\AppData\Roaming\npm\node_modules\jsdoc\templates\default\static\styles with this file https://github.com/gm2008/jsdoc/blob/master/templates/default/static/styles/jsdoc-default.css

That's it.

Question 2

I have had to go down the route of creating the functions outside of the type above and calling those functions in such things as .run or factories etc.

/**
 * @author Example <jon.doe@example.com>
 * @copyright 2014 Example Ltd. All rights reserved.
 */
(function () {
    window.example = window.example || {};
    /**
     * Example Namespace
     * @memberOf example
     * @namespace example.angular
     */
    window.example.angular = window.example.angular || {};
    var exAngular = window.example.angular;
    /**
     * My example bootstrap run function
     * @param  {object} $http    {@link http://docs.angularjs.org/api/ng.$http}
     * @param  {[type]} $cookies {@link http://docs.angularjs.org/api/ngCookies.$cookies}
     */
    var runFunction = function ($http, $cookies) {
        $http.defaults.headers.post['X-CSRFToken'] = $cookies.csrftoken;
        $http.defaults.headers.common['X-CSRFToken'] = $cookies.csrftoken;
    };

    /**
     * A Example Angular Bootstrap Module
     * @memberOf example.angular
     * @namespace example.angular.bootstrap
     * @function bootstrap
     * @example
     *     &lt;div ng-app="exampleAngularBootstrap"&gt;
     *         &lt;div ng-view&gt;&lt;/div&gt;
     *     &lt;/div&gt;  
     */
    exAngular.bootstrap = angular.module('exampleAngularBootstrap', [
            'ngRoute',
            'ngResource',
            'ngCookies'
        ])
        .run(runFunction);
})();