angularjs ngdoc

Starting off with NgDocs

By James Martin, published Monday, January 5th, 2015

Tweet

inShare4

---

Documenting code is important – if you’re working in a team, it allows colleagues who perhaps weren’t involved in the original development to see what goes where, and even if you’re lone wolf-ing it, it always helps to have a reminder of what a function does.

There are plenty of standards for commenting code – for Javascript, the most common choice is JSDoc.

AngularJS is written in Javascript, but it’s structure is so different and well defined, it now has its own style of JSDocs called NgDocs.

The greatest thing about NgDocs, is that there are generators to build documentation sites which are very similar to the official Angular documentation.

There are two main ones, ngdocs and Ngeni – in this post, we will be covering the former, as it has better documentation, although it is worth pointing out that Ngeni is what the Angular docs are actually written in.

Grunt

For a brief overview, grunt is a ‘build system’, which esentially means it does all of the boring, menial, repetitive tasks for you in regards to developing and releasing your web app.

There is a grunt plugin available for ngDocs here.

Configuring this is rather simple, and here’s a snippet of code to help you get started:

ngdocs: {   options: {       dest: 'docs',       html5Mode: false,       scripts: [           'bower_components/angular/angular.js',           'bower_components/angular-animate/angular-animate.js'       ]   },   api: {       src: ['app/**/*.js', '!app/**/*-spec.js'],       title: 'Docs'   }}

Much of the above should hopefully be rather self-explanatory, however there are a couple of lines I’ll point out:

• html5Mode: false: this makes it so that the URL is domain.tld/#/page, rather than domain.tld/page. Whilst this might seem a little weird, it’s more out of personal preference than anything – it’s mainly relevant if you want to support older browsers, as quite a few versions of IE will not support HTML5 mode.
• scripts: ngDocs will include some version of angular for you, however at the time of writing, they’re a version behind, and so if you plan to use embedded examples (a way you can have actual working examples of your directives in your docs) then you’ll want to try and make sure that you include the same version of Angular your project uses.
• api: this is our grunt target – it enables us to have more than one doc set if we like. Here you can see we’re excluding out test files (suffixed -spec.js) from the docs.

To run and build your docs, execute grunt ngdocs:api from your command line (or simply grunt ngdocs if you only have one target). This should output the entire docs app (ironically, another angular app!) into the /docs folder (or wherever you specified).

Documenting Code

There are two main sources of information on writing ngDocs, Angular’s own wiki, and idanush’s github. Both of these are great, but in some places they conflict with each other, and can sometimes lead to extra frustration.

Below, I will briefly outline how to document each component of a Angular app, but if there’s anything you feel I’ve missed, visiting either of the above two sources will probably help, but my personal recomendation is that you go straight to the AngularJS source code and look at how they’ve documented things.

Directives

Below is an example of how to document a directive:

/**     * @ngdoc directive     * @name global.directive:nameOfDirective     * @scope     * @restrict E     *     * @description     * A description of the directive     *     * @param {object}  field   A field object     *     */

• The @ngdoc annotation tells ngDocs that this is a directive.
• The name must contain the current module, and the word ‘directive’, followed by a : and the name of the directive. This seems rather weird, since you’ve already told ngDocs that you’re looking at a directive, but hey, whatever.
• @scope denotes that this directive has an isolate scope. If your directive isn’t isolate, just leave this annotation off completely.
• @restrict E should match your restrict option of the directive, e.g. EAC. This will tell ngDocs to render the correct usage examples, which is awesome.
• @description
• @param has a very strict format. It has to go @param {type} name description. The type must be in curly braces. Optional parameters are indicated by an = after the type, so {type=}. Name and description are also both mandatory. You can have as many params as you need.

Controllers, Filters and Services

/** * @ngdoc controller * @name dashboard.controller:ControllerName * @description * A description of the controller, service or filter */

Everything else take the same essential information. Obviously, if you’re documenting a filter or service, replace all references to controller with that item instead.

You can also document properties and methods of anything (controllers, filters, services etc), and we’ll cover that later.

Methods and Properties

Documenting methods and properties of something are roughly handled the same, but there are a couple of extra annotations you’ll need to remember.

/** * @ngdoc method * @name methodName * @methodOf module.ControllerName * @description * Describe the method here... * * @param {string} Description of parameter * @returns {Array} The returned item... */

The most important new property here is methodOf, which is particularly important – it must be the same as the name of the directive/service/controller/whatever you’re currently documenting, as this seems to be the only way that ngDocs can match the two together.

Properties are the same, except they don’t take @param and @returns, and instead of @methodOf, you use @propertyOf, and the ngdoc type of property.

Note: It’s worth noting that the format of @returns is the same as @param

Generating the docs

When you’re happy that everything’s been sufficiently documented (or, if you just feel like going crazy), you can make grunt generate the documentation app with this command:

grunt ngdocs

You’ll see some output similar to this:

In our example at the very top, we configured the dest folder to be ‘docs’, so if you go into your project and look at the docs folder, you should see an index.html file, and a few folders. Crack open the champagne, because that’s your documentation!

To view it, assuming you’re using grunt to serve, go to http://localhost:9000/docs. Alternatively, if you have some sort of virtual host set up, you can try http://myapp.dev/docs, or configure it any other way to suit your needs.

Tips

Watch

If you’re using grunt to serve your Angular application, like most people are, then you may want to add ngdocs to the list of tasks executed when a file is changed.

It may sound painfully slow, but in my experience it normally takes less than a second, often closer to half a second. Sure, it could get painful after a while, but at least if you’re in the process of documenting an entire app (because you were too lazy to do it as you wrote it!), its definitely a valuable way to save time.

Linking

You can link to other pages of your own documentation, or external pages, using the {@link} syntax. e.g:

{@link module.directive:DirectiveName DirectiveName}

This will make a link to your ‘directiveName’ page. Very helpful for linking related components togeter.

Link also accepts external URLs if you wish to link to, say, a library you used.

ngDocs is a great way to view docs, as it lets you filter and search through all your documentation, and provides a very nicely formatted way to view something typically very…dry, like API documentation.

It’s so simple to implement, and follows a fairly well defined and strict standard, so your code will fit right in with the AngularJS community.

Tags: Angular, AngularJS, development, Documentation, ngDocs