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,
- There is no need to maintain separate files for keeping documentation
- Whenever the developer is making the changes to source code, he can immediately update the comment also so that the document will be updated.
- 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
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)
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
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.
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
A sample implementation is given below:
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.
A sample implementation is given below:
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
A sample implementation is given below.
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:
Happy Learning