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

• @name documentName
• @param {type} name description
• @returns {type} description
• @requires
• @property
• @desc
• @dep

The type must be in {} curly braces Parameters can be made optional by putting [name] in square brackets Descriptions can contain markdown

@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>