AngularJS Documentation Generation Code

July 24, 2015

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 are kept in sync as the code changes.

This is the most important link, clear example of how to do it:

Contents

ngdoc

The flavour of jsdoc used by AngularJS is called ngdoc and is parsed by a Node.js utility called Dgeni. The documentation is best built using grunt:

grunt package

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

Dgeni installation

n the project you want to document you install Dgeni by running:

$ npm install dgeni --save-dev

This will install Dgeni and any modules that Dgeni depends upon.

Key concepts

  • Processors
  • Services
  • Packages

Processors

Building blocks of doc generation.

Services

Singleton helper objects.

Packages

Reusable component containers.

Depency injection in Dgeni

Everything in dgeni is an injectable component created by a factory function:

  • processors
  • services
  • config blocks

Creating Packages

processors, services, config and templates are grouped into packages.

var p = new Package('docPackage',['jsdoc']).
        .factory(require('./services/myService')
        .config(function(templateFinder){
                templateFinder.tempateFolders = ['./templates'];
        });

Defining servicies

Simply export a factory function from a module.

module.exports = function log(){
        return function(message){
                console.log(message);
        };
};

Processors

module.exports = function filterNgDocsProcessor(log){
        return {
                $runAfter: ['tags-parsed'],
                $runBefore: ['extracting-tags'],
                $process: function (docs){
                        var = filteredDocs = _.filter(docs, function(doc){
                                return doc.tagas.getTag('ngdoc');
                        });
                        log.debug('filtered '+(docs.length-filteredDocs.length));
                        return filteredDocs;
                }
        };
}

Running dgeni

var Dgeni = require('dgeni');
var myPackage = require('./myPackage');
var dgeni = new Dgeni([myPackage]);

dgeni.generate().then(function (){
        //...
});

dgeni-packages

dgeni-packages

  • base - basic document processing
  • jsdoc - JSDoc style @tags
  • nunjucks - template based rendering
  • ngdoc - processing for the AngularJS project
  • examples - inline runnable examples (and tests)