Ngdoc documentation for controller

Question

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

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

There is no documented controller in this example, so I added my own documented controller using this code:

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

When I try to create 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 to fix it? I read this guide http://www.shristitechlabs.com/adding-automatic-documentation-for-angularjs-apps/ and I can’t understand why I keep getting an error message if I try to document the controller :( Thanks for any help!

Answer 1

It looks like the repo example has an obsolete version of grunt-ngdocs , indicated as a dependency. @ngdoc controller supported since 0.2.2, and grunt-ngdocs-example is 0.1.1. Use the latest grunt-ngdocs and you should be fine.

It should be noted that the “official” Angular documentation tool is dgeni + dgeni-packages . It is used by Angular 1.x to create its own documentation. Very flexible and extensible, although installation may take some time.

---

Edit I forked out grunt-ngdocs-example here , updated the version of grunt-ngdocs and added an example controller.

Answer 2

Here's how you can document a 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 3

Use dgeni and add a user controller template:

• Create controller.template.html in config/template/ngdoc/api with content {% extends "api/object.template.html" %} (it inherits the object template, but you can write your own template)

• Go into dgeni configuration and expand idTemplates in computeIdsProcessor

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

• 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' });})