如何使用JSDoc注释AngularJS组件

Question

我们应该使用什么标签来用JSDoc记录Angular JS组件？ 我当时在考虑使用@module，对吗？

例如 ：

/**
* @module helloWorld
*
* @description AngularJS component to display a message with a name.
*
*/
angular.component('helloWorld', {
  bindings: {
    name: '@'
  },
  controller : function helloWorldCtrl () {
    this.logName = logName;

    /**
     * @function logName
     *
     * @param {string} msg - message to display with the name.
     *
     * @memberof helloWorld
     *
     * @description Log in the console the message with the name.
     *
     */
    function logName(msg) {
      console.log(msg + this.name);
    }
  },
  template : '<div><span ng-click="$ctrl.logName('Hi ')">{{$ctrl.name}}!</span></div>'
});

对于指令，服务和控制器，我会有同样的问题。 另外我使用@memberof的方式对吗？

Answer 1

尽管JSDoc确实具有@module ，但这是一个“可见性”规范，我认为这不是您要寻找的。

@module标记将当前文件标记为它自己的模块。 除非另有说明，否则假定文件中的所有符号都是模块的成员。

这可能是正确的，但也可能不是。

您需要记住的关键是，这些批注应充当痕迹，以便可以在文档中链接继承的行为，还可以使编译器获得有关代码的尽可能多的信息。

因此，当寻找如何记录这一点时，我会在Angular externs和@return / @type / @param @type匹配的部分；

@return {angular.Component} Component definition object.

希望有帮助！

Answer 2

首先，在文档中定义单独的主题以列出所有模块。 为此，创建一些带有下一个注释的空文件：

/**
 * @namespace solution_name
 */ 

对于模块，可以使用此注释在其单独的html页面中定义每个模块

/**
 * @class solution_name.MyModule
 * @memberOf solution_name 
 */

服务注释将作为myModule页面文档的一部分添加

/**
 * @function myService
 * @memberOf solution_name.MyModule
 * @description This is an my service.
 */

控制器可以这样装饰，也可以在模块文档页面中单独列出

/**
 * @class solution_name.MyModule.MyController
 */

要创建树形结构以合并控制器，基于业务的服务需要，您还可以根据类/函数定义添加namespace属性

/**
 * @namespace MyApp.Controllers
 */