控制器的ngdoc文档

Question

我刚开始编写文档代码，并试图用grunt-ngdocs来记录我的专业应用程序。

我从以下https://github.com/m7r/grunt-ngdocs-example中克隆了一个工作示例

给出的示例缺少一个有文档的控制器，因此我在下面的代码中添加了自己的文档控制器：

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

当我试图通过从命令行运行grunt来构建文档时，我会得到以下错误消息：

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

我该怎么解决这个问题？我阅读了这个指南http://www.shristitechlabs.com/adding-automatic-documentation-for-angularjs-apps/，我不知道为什么我总是收到错误信息，如果我试图记录一个控制器:(谢谢您的帮助！

Answer 1

看来，回购示例有一个过时的grunt-ngdocs版本，作为依赖项列出。@ngdoc controller的支持值为0.2.2，而grunt-ngdocs-example列出了~0.1.1。使用最新的grunt-ngdocs，你应该可以走了。

值得一提的是，生成角文档的“官方”工具是德根尼 + dgeni包。它被角1.x用来生成自己的文档。非常灵活和可扩展，尽管设置可能需要一些时间。

编辑我已经分叉了grunt-ngdocs-example 这里，升级了grunt-ngdocs版本并添加了一个控制器示例。

Answer 2

下面是如何记录示例控制器的方法：

/**
 * @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

使用德根尼并添加自定义控制器模板：

1. 用内容controller.template.html在config/template/ngdoc/api中创建{% extends "api/object.template.html" %} (它将继承对象模板，但您可以编写自己的模板)
2. 转到dgeni配置并在idTemplates中扩展computeIdsProcessor 配置(computeIdsProcessor) {computeIdsProcessor.idTemplates.find (idTempl) {返回idTempl.idTemplate ===“模块：${idTempl}.${docType}：${name}”；}).docTypes.push(“控制器”)；})
3. 记住在"controller"中包括computePathsProcessor 'partials/${area}/${module}/${docType}/${name}.html‘(computePathsProcessor) { computePathsProcessor.pathTemplates.push({ docTypes：'provider’、‘服务’、‘指令’、‘输入’、'object‘、'function’、'filter‘、'type’、‘控制器’、pathTemplate：‘${area}/${/${docType}/${name}’、outputPathTemplate: outputPathTemplate });})