Nick White Nick White - 1 year ago 152
AngularJS Question

JSDoc with AngularJS

Currently within my Project we are using JSDoc, we have recently started to implement Angular and I want to continue using JSDoc to ensure that all the documentation is within the same place.

I have taken a look at people mainly just saying to use ngDoc but this isn't really a viable option as we will always have separate JavaScript and I ideally would have everything together.

* @author Example <>
* @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;

* A Example Angular Bootstrap Module
* @module exampleAngularBootstrap
exAngular.bootstrap = angular.module('exampleAngularBootstrap', [
.run(function ($http, $cookies) {
$['X-CSRFToken'] = $cookies.csrftoken;
$http.defaults.headers.common['X-CSRFToken'] = $cookies.csrftoken;

Currently this is what I have but am unable to put documentation for the run() any ideas?

Answer Source

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.Furthermore, 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.

I like using jsdoc to document angularjs codes because the module-service-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

That's it.

Recommended from our users: Dynamic Network Monitoring from WhatsUp Gold from IPSwitch. Free Download