A comprehensive guide to understanding controllers: ngdoc documentation

Question

A comprehensive guide to understanding controllers: ngdoc documentation

I am new to code documentation and currently attempting to document my Angular application using grunt-ngdocs.

After cloning a functional example from: https://github.com/m7r/grunt-ngdocs-example, I noticed that the provided example did not include documentation for a controller. Thus, I decided to add my own documented controller with the following code:

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

However, when attempting to generate documentation by running grunt from the command line, an error message is displayed:

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

I have consulted this guide but I cannot seem to resolve why I keep encountering errors while trying to document a controller. Any assistance would be greatly appreciated! Thanks!

javascript angularjs documentation-generation ngdoc grunt-ngdocs

Answer 1

Answer №1

Below is a guide on how to document a sample controller:

/**
 * @ngdoc function
 * @name appModernizationApp.controller:DetailsCtrl
 * @description
 * # DetailsCtrl
 * Controller of the appModernizationApp
 * This particular controller is in charge of displaying the details of the page.
 * It starts by fetching the JSON data for the different room types from the server upon initialization.
 * Additionally, it also requests the details of a specific room for an existing reservation if there is a reservation id 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 Manages the top navigation at the page level.
 * @property {array} reservationDetails:array Contains the reservation details of the current/selected reservation.
 * @property {string} registerationErrorMsg:string Stores error messages related to registration services.
 * @property {string} roomSearchErrorMsg:string Stores error messages related to room search services.
 * @property {array} roomDetails:array Holds the room details object. This object is directly retrieved from the service response and may be manipulated based on the view model.
 * @property {boolean} submitted:boolean Tracks the submission status. Initialized as false and set to true after storing the details.
 * @property {number} reservationId:number Retrieves the reservation id from the route parameters.
 * @property {date} minDate:date Represents the minimum date value filled in.
 * @property {boolean} isRoomDetailsVisible:boolean Manages the visibility of room details through a boolean flag. Initially set to false.
 * @property {array} roomTypes:array Stores the types of rooms obtained from the JSON data.
 * @property {array} expirymonth:array Lists months from January to December
 * @property {array} expiryYear:array Includes years within a specific range
 * @property {array} cardtype:array Specifies the types of cards available
 */

Answer 2

Below is a guide on how to document a sample controller:

/**
 * @ngdoc function
 * @name appModernizationApp.controller:DetailsCtrl
 * @description
 * # DetailsCtrl
 * Controller of the appModernizationApp
 * This particular controller is in charge of displaying the details of the page.
 * It starts by fetching the JSON data for the different room types from the server upon initialization.
 * Additionally, it also requests the details of a specific room for an existing reservation if there is a reservation id 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 Manages the top navigation at the page level.
 * @property {array} reservationDetails:array Contains the reservation details of the current/selected reservation.
 * @property {string} registerationErrorMsg:string Stores error messages related to registration services.
 * @property {string} roomSearchErrorMsg:string Stores error messages related to room search services.
 * @property {array} roomDetails:array Holds the room details object. This object is directly retrieved from the service response and may be manipulated based on the view model.
 * @property {boolean} submitted:boolean Tracks the submission status. Initialized as false and set to true after storing the details.
 * @property {number} reservationId:number Retrieves the reservation id from the route parameters.
 * @property {date} minDate:date Represents the minimum date value filled in.
 * @property {boolean} isRoomDetailsVisible:boolean Manages the visibility of room details through a boolean flag. Initially set to false.
 * @property {array} roomTypes:array Stores the types of rooms obtained from the JSON data.
 * @property {array} expirymonth:array Lists months from January to December
 * @property {array} expiryYear:array Includes years within a specific range
 * @property {array} cardtype:array Specifies the types of cards available
 */

Answer 3

Answer №2

The example repository seems to have an outdated version of grunt-ngdocs listed as a dependency. The latest @ngdoc controller is supported in version 0.2.2, while the repository lists ~0.1.1. Upgrading to the newest version of grunt-ngdocs should resolve this issue.

It's important to note that the recommended tool for generating Angular documentation is dgeni along with dgeni-packages. This combination is used by Angular 1.x for its own documentation generation. Despite its flexibility and extensibility, setting it up may require some time.

Edit: I have forked the grunt-ngdocs-example repository here, updated the grunt-ngdocs version, and included a controller example.

Answer 4

The example repository seems to have an outdated version of grunt-ngdocs listed as a dependency. The latest @ngdoc controller is supported in version 0.2.2, while the repository lists ~0.1.1. Upgrading to the newest version of grunt-ngdocs should resolve this issue.

It's important to note that the recommended tool for generating Angular documentation is dgeni along with dgeni-packages. This combination is used by Angular 1.x for its own documentation generation. Despite its flexibility and extensibility, setting it up may require some time.

Edit: I have forked the grunt-ngdocs-example repository here, updated the grunt-ngdocs version, and included a controller example.

Answer 5

Answer №3

Utilize dgeni to incorporate a custom controller template:

Create a file named controller.template.html within the directory config/template/ngdoc/api. Include the content
```
{% extends "api/object.template.html" %}
```
(this will inherit from the object template allowing you to write your own custom template)

In the dgeni configuration, expand the idTemplates in the computeIdsProcessor

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

Don't forget to include "controller" in the 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'
});})

Answer 6

Utilize dgeni to incorporate a custom controller template:

Create a file named controller.template.html within the directory config/template/ngdoc/api. Include the content
```
{% extends "api/object.template.html" %}
```
(this will inherit from the object template allowing you to write your own custom template)

In the dgeni configuration, expand the idTemplates in the computeIdsProcessor

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

Don't forget to include "controller" in the 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'
});})

A comprehensive guide to understanding controllers: ngdoc documentation

Answer №1

Answer №2

Answer №3

Similar questions

Ways to update the value within an object in an array stored in a BehaviorSubject?

Switch out the image source and add attributions until the AJAX call is complete

I've come across some strange JavaScript code while tinkering with an Express/Socket.io application

applying various conditions to JavaScript arrays for filtering

How to deactivate a button in AngularJS after it has been clicked

Tips for modifying HTML elements and navigating to a different webpage

Having trouble with calling an AngularJS API URL?

Remove each notification automatically in JavaScript after a specified period of time

Can express middleware be tailored for each individual handler within the same route path?

What about creating a PHP-MySQL voting platform?

Guide on showcasing an array in a table using DataTables in a single column

Is there a way to retrieve JSON data using Vue and Axios?

Is there a way to add a sub-heading into the side menu?

React - A guide on accessing the scroll position of a div using JavaScript

Is there a way to get a Chrome extension to run automatically in the background?

Creating a custom HTML5 pattern for formatting Pakistani phone numbers

Transform an image into Base64 format by effortlessly dragging and dropping

"Bower fetches and installs specific versions of packages from the repository

Utilizing jQuery and JSON to showcase the contents of an array

Running on Node.js, the Promise is activated, yet there remains an issue with the function