如何为 Angular 组件注释 ngdoc？

Posted 2023-03-13

【中文标题】如何为 Angular 组件注释 ngdoc？

【英文标题】：How to annotate ngdoc for an Angular component?

【发布时间】：2017-01-04 12:07:44

【问题描述】：

我正在编写一个 AngularJS 组件，我想知道将 ngdoc 注释添加到组件本身和控制器功能的正确方法是什么。

你有例子吗？

【问题讨论】：

澄清一下：您要问的是，当您使用 .component() 方法编写 Angular 1.5.x 组件时，对吧？

【参考方案1】：

这里有一个例子：

controller.js::

/**
 * @this vm
 * @ngdoc controller
 * @name dragDropRelation.controller:draggableItemController
 *
 * @description
 *  Controller for the draggableItem component
 */
export default function draggableItemController() 

component.js：

import controller from './controller.js';
import templateUrl from './view.html';
/**
 * @ngdoc component
 * @name dragDropRelation.component:draggableItem
 *
 * @description
 * Component that allows to be dragged containing some data.
 * @param Boolean used Used flag
 * 
 * @param String text Text to display
 * @param Object data Data to be saved
 * 
 * @param Boolean disabled variable to disable the component
 */
export const component = 
  templateUrl: templateUrl,
  controller: controller,
  bindings: 
    used: '<?',
    text: '<',
    data: '<',
    disabled: '<?',
  ,
;

module.js:

import angular from 'angular';
import angularDragDrop from 'angular-drag-drop';
import component from './component.js';


/**
 * @ngdoc overview
 * @name dragDropRelation.module:draggableItem
 *
 * @description
 * Module that contains the component draggableItem
 * 
 * @example
 *  <b>script.js</b>
 *  <pre>
 *  import draggableItem from 
 *    './components/drag-drop-relation/draggable-item/module'
 *  angular.module('myModule', [draggableItem]);
 *  </pre>
 * 
 */
export default angular
  .module('draggableItem', [angularDragDrop])
  .component('draggableItem', component)
  .name;

这将生成类似这样的内容（使用 gulp-ngdocs）：

（我原来的组件文档是西班牙语）

【参考方案2】：

据我所知，您不能用ng-doc 的主要版本记录components。

Serenity-Frontstack 制作了一个 ng-doc 的分支并支持 Angular 组件：

* @ngdoc component
* @name app.component:guideItem
*
* @description
* This component shows cards using the item binding for his own building.
*
* @param object  item      A object with card data 

【参考方案3】：

您应该使用@ngdoc overview 来定义模块。 @ngdoc controller 用于控制器，@ngdoc service 用于服务。

模块

/**
 * @memberof dugun.leads
 * @ngdoc module
 * @description
 * Leads mean info requsts and inbound calls
 */
angular.module('dugun.leads', [
    // vendor
    'ngRoute',
    'dugun.notifications',
    'dugun.queryString',
    'dugun.search',
    // app
    'dugun.helpers.tableSort',
    'dugun.forms',
    'dugun.leads.infoRequests',
    'dugun.leads.calls'
]);

路线

/**
 * @memberof dugun.leads
 * @ngdoc route
 * @name LeadRoutes
 * @param $routeProvider provider $routeProvider
 *
 * @description /providers/:providerId/info
 */
function LeadRoutes($routeProvider) 
    $routeProvider
        .when('/leads', 
            templateUrl: 'leads/list.html',
            controller: 'LeadListCtrl',
            controllerAs: 'leadListCtrl',
            label: 'Çiftler',
            reloadOnSearch: false
        );

控制器

/**
 * Controls Provider
 * @constructor
 * @ngdoc object
 * @memberof dugun.leads
 * @name LeadListCtrl
 * @scope
 * @requires $scope service controller scope
 * @requires $route service $route
 * @requires $window service $window
 * @requires $filter service $filter
 * @requires dgNotifications service dgNotifications
 * @requires moment service moment
 * @requires queryString service dugun.queryString:queryString
 * @requires Analytics
 * @requires Leads factory Leads service
 */
function LeadListCtrl($scope, $route, $window, $filter,
                      dgNotifications, queryString, moment, Analytics,
                      Leads)

【讨论】：

我认为问题是，如何在 Angular 1.5.x 中将 ng-doc cmets 添加到 .component()。我不确定我是否遵循您对这个问题的回答？你能澄清一下吗？