No comments yet

Adding Automatic Documentation for AngularJS Apps

This blog is to show how to add automatic documentation for Angular Apps using ng-doc

If you have been playing around with AngularJS, you might be already knowing that AngularJS documentation is being generated automatically. AngularJS team has created a documentation creation utility module on top of jsdoc, which is called ng-doc

In this way of documentation, all the documentation is added in source code itself. There are some benefits we are getting out of it. First of all,

  1. There is no need to maintain separate files for keeping documentation
  2. Whenever the developer is making the changes to source code, he can immediately update the comment also so that the document will be updated.
  3. Adding a demo for each component is very easy.

There are both grunt and gulp plugins are available for ng-docs. Today we will see how to setup ng-docs in grunt. I assume that you have some basic knowledge on Grunt

How to set up grunt-ngdocs

    Install grunt-ngdocs using the following command

    npm install grunt-ngdocs –save-dev 

    Once that’s done, add this line to your project’s Gruntfile:

    grunt.loadNpmTasks(‘grunt-ngdocs’);

    Inside your gruntfile (Gruntfile.js), you can setup options for ngdocs

    1 angular.js

     

    In this, you can see I have given some options. Lets go through one by one

    Title: The title to be displayed for the documentation app

    Scripts:  All the required files to run the app

    HTML5Mode: Option to set whether you want your documentation app to contain ‘#’ in the urls. If you set to false, url will be having ‘#’

    All: The files which will have your documentation. In this case, I have added documentation in several files in scripts folder. So, I have set all JS files in scripts folder.

    By default, the documentation app will be created in docs folder

    Now, you have to register this task to grunt (Gruntfile.js)

    2 angular.js bangalore

    You can see that, I have mentioned several tasks like clean, html2js, ngdocs and connect. In this, ngdocs is the task for ngdoc.

    ‘clean’ task is to clear all files in docs folder.

    ‘html2js’  task is to convert all partials to a single JS module.

    ‘connect’ task is to start a local server.

    Now that the task is setup, let us see how to add the documentation for each component.

 

Controller

     3 angular.js training image

    ngdoc fully relies on the naming conventions. If you are writing a documentation for a controller, you have to start with @ngdoc controller

    @name parameter for controller expects modulename.controller:controllerName

    ngdoc will understand that this is a controller only by putting modulename.controller in the name.

    A sample implemenation is given below.

    Here ‘MyCtrl’ is the controller name and ‘myapp’ is the module name.

    You can see the full implementation here.

    4 angular.js institutes in bangalore

    Directive

    Directive naming also is in the same format. However, the @ngdoc type will be @ngdoc directive

    @name is expecting moduleName.directive:directiveName

    @restrict is to specify the restrict options of the directive

    @scope add this only if the directive is isolated scope

    @param is to specify all the scope parameters of an object.

    The format is @param {type} nameOfParameter Description

    type can be String, Object, Array, Boolean. If this is an optional parameter, you can give = also along with the type. So, for example, if the parameter name is ‘param1’ and type is String and is optional, you can give

    @param {String=} param1 Description of param1

    @example is for showing a sample implementation

    5 anglularjs training

    A sample implementation is given below:

    6 angularjs training in bangalore

    In this case, ‘myapp’ is the module name and ‘myDirective’ is the directive name.

    You can see the full implementation details here:

    Service

    Service documentation is pretty simple.

    @ngdoc type should be @ngdoc service

    @name format is moduleName.service:serviceName.

    7 angularjs training bangalore

    A sample implementation is given below:

    8 angularjs online training

    In this case ‘myapp’ is the module name and ‘MyService’ is the service name.

    You can see the full implementation details here:

 

Methods

    You can add documentation for individual methods also. Then the @ngdoc type will be @ngdoc method.

    The two new annotations  in method are @methodOf and @returns.

    @methodOf is a very important annotation. The name you are giving here should be exactly same as the @name you have given for the component

    9 angularjs training institute

    A sample implementation is given below.

    10 angular.js training

    Here ‘getUsers’ is the name of the method. You can see that @methodOf value is ‘myapp.service:MyService’ which is exactly how we have given the value for @name annotation for  ‘MyService’ in the documentation.

    By

    Jinto Jose

 
Reference Links:

  1. Writing AngularJS-Documentation
  2. Ngdocs

 

Happy Learning

Post a comment to Anonymous

{"wp_error":"cURL error 60: SSL certificate problem: certificate has expired"}