如何使用 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

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

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

要创建树结构以根据业务需求组合控制器和服务，您还可以根据您的 class/function 定义添加 namespace 属性

/**
 * @namespace MyApp.Controllers
 */

Answer 2

尽管 JSDoc 确实有 @module，但它是一个 "visibility" 规范，我认为这不是您要找的。

The @module tag marks the current file as being its own module. All symbols in the file are assumed to be members of the module unless documented otherwise.

这可能是真的，但也可能不是。

您需要记住的关键是，这些注释应充当面包屑路径，以便可以在文档中链接到继承的行为，并且编译器可以获得尽可能多的代码信息。

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

@return {angular.Component} Component definition object.

希望对您有所帮助！

如何使用 JSDoc 注释 AngularJS 组件

How to comment AngularJS component with JSDoc

javascript

jsdoc

angularjs