ngdoc documentation for controller

Question

I am to new to code documentation and trying to document my angular application with grunt-ngdocs.

I cloned a working example from: https://github.com/m7r/grunt-ngdocs-example

The given example lacks a documented controller so I added my own documented controller with this code:

 /**
  * @ngdoc controller
  * @name rfx.controller:testCtrl
  * @description 
  * Description of controller.
  */
 .controller('testCtrl', function() {
 });

When I am trying to build a documentation by running grunt from the command line I get the following error message:

Warning: Don't know how to format @ngdoc: controller Use --force to continue.

How do I fix this? I read this guide http://www.shristitechlabs.com/adding-automatic-documentation-for-angularjs-apps/ and I can't figure out why do I keep getting error message if I try to document a controller :( Thanks for any help!

Answer 1

Here is how you can document sample controller:

/**
 * @ngdoc function
 * @name appModernizationApp.controller:DetailsCtrl
 * @description
 * # DetailsCtrl
 * Controller of the appModernizationApp
 * This controller is responsible for showing the details of the page.
 * It gets initialized by requesting the JSON for types of rooms which is hosted on the server.
 * It also requests for the details of the room for an existing reservation if the reservation id is present in the route using <b>HRS.getRegisteredData(reservationId)</b>.
 * @requires $scope
 * @requires $http
 * @requires HRS
 * @requires $location
 * @requires $routeParams
 * @requires breadcrumbs
 * @requires UtilitiesService
 * 
 * @property {object} breadcrumbs:object breadcrumbs Handles the page level/navigation at the top.
 * @property {array} reservationDetails:array This holds the reservation details of the current/selected reservation.
 * @property {string} registerationErrorMsg:string This variable holds the error message for all registration services.
 * @property {string} roomSearchErrorMsg:string This variable holds the error message for all room search services.
 * @property {array} roomDetails:array This holds the room details object. This will be a fresh object coming from service response and will be manipulated as per the view model.
 * @property {boolean} submitted:boolean Holds the submitted boolean flag. Initialized with false. Changes to true when we store the details.
 * @property {number} reservationId:number Gets the reservation id from the route params.
 * @property {date} minDate:date Date filled in the minimum date vatiable
 * @property {boolean} isRoomDetailsVisible:boolean Controls the boolean flag for visibility of room details. Initialized with false.
 * @property {array} roomTypes:array Holds types of rooms from JSON.
 * @property {array} expirymonth:array Months from Jan to Dec
 * @property {array} expiryYear:array Years of a particular range
 * @property {array} cardtype:array Type of cards
 */

Answer 2

It appears that the example repo has an out-of-date version of grunt-ngdocs listed as a dependency. @ngdoc controller is supported as of 0.2.2, while grunt-ngdocs-example lists ~0.1.1. Use the latest grunt-ngdocs and you should be good to go.

It's worth mentioning that the "official" tool for generating Angular documentation is dgeni + dgeni-packages. It is used by Angular 1.x to generate its own documentation. Very flexible and extensible, although the setup can take some time.

---

Edit I've forked grunt-ngdocs-example here, upgraded the grunt-ngdocs version and added a controller example.

Answer 3

Use dgeni and add custom controller template:

1. Create controller.template.html in config/template/ngdoc/api with content {% extends "api/object.template.html" %} (it will inherit from object template but you can write your own template)

2. Go to your dgeni config and extend idTemplates in computeIdsProcessor

   config(function (computeIdsProcessor) {
   computeIdsProcessor.idTemplates.find(function (idTempl) {
       return idTempl.idTemplate === "module:${module}.${docType}:${name}";
   }).docTypes.push("controller");})
   

3. Remember to include "controller" in computePathsProcessor

   .config(function (computePathsProcessor) {
   computePathsProcessor.pathTemplates.push({
       docTypes: ['provider', 'service', 'directive', 'input', 'object', 'function', 'filter', 'type', 'controller'],
       pathTemplate: '${area}/${module}/${docType}/${name}',
       outputPathTemplate: 'partials/${area}/${module}/${docType}/${name}.html'
   });})