Writing AngularJS Documentation

The AngularJS project uses a form of jsdoc for all of its documentation.

This means that all the docs are stored inline in the source code and so is kept in sync as the code changes.

It also means that since we generate the documentation from the source code, we can easily provide version specific documentation, by simply checking out a version of AngularJS and running the build.

Using ngdoc

The flavour of jsdoc used by AngularJS is called ngdoc and is parsed by a nodejs utility stored in the AngularJS project itself under the /docs/src folder. There are test specs for this utility in /docs/spec. The documentation is best built using grunt:

grunt release

This will generate all the AngularJS distribution files and also the documentation. Look for them inside /build/docs.

Note: ngdoc and its processing utility is only related to the documentation of the AngularJS project and is not part of the AngularJS distribution JavaScript files.

Standard supported jsdoc directives

The ngdoc utility has basic support for many of the standard jsdoc directives. But in particular it is interested in the following directives:

• @name name - the name of the ngdoc document
• @param {type} name description - describes a parameter of a function
• @returns {type} description - describes what a function returns
• @requires - normally indicates that a JavaScript module is required; in an Angular service it is used to describe what other services this service relies on
• @property - describes a property of an object
• @description - used to provide a description of a component in markdown
• @link - specifies a link to a URL or a type in the API reference

The type must be wrapped in {} curly braces; e.g. {Object|Array} Parameters can be made optional by putting the [name] in square brackets; e.g. @param {boolean} [ownPropsOnly=false] Descriptions can contain markdown formatting

AngularJS specific ngdoc directives

In addition to the standard jsdoc directives, there are a number that are specific to the Angular code-base. First there are ones for describing AngularJS directives:

• @scope - specifies that the directive will create a new scope
• @priority - specified the directive's priority

Writing examples and e2e scenarios

It is possible to embed examples in the documentation along with appropriate e2e scenarios. These examples and scenarios will be converted to runnable code within the documentation. So it is important that they work correctly. To ensure this, all these e2e scenarios are run as part of the automated test tasks in Travis and the CI server.

@section [file.ngdoc]
@section api ...
@ngdoc
@example
{@type type [url]}
{@link url [title]}

<example module="..." deps="..." animation="true|false"> <!-- Create a new example scenario -->
  ...
</example>

<pre>...</pre>

<doc:example module="...">
  ...
  <doc:source>
    ...
    <script></script> <!-- Contents will be extracted into a script.js file -->
    ...
    <style></style> <!-- Contents will be extracted into a style.css file -->
    ...
  </doc:source>
  ...
  <file src="..." tag="..." name="...">
    ... <docs tag="...">...</docs> ...
  </file>
  ...
</doc:example>

<file src="..." tag="..." name="...">
  ... <docs tag="...">...</docs> ...
</file>

<docs tag="...">...</docs>