如何使用 JSDoc 注释 AngularJS 组件答案

【问题标题】：How to comment AngularJS component with JSDoc如何使用 JSDoc 注释 AngularJS 组件
【发布时间】：2017-05-25 23:54:21
【问题描述】：

我们应该使用什么标签来用 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的方式对吗？

【问题讨论】：

您是否已经看过ngdocs 或angular-jsdoc？两者都使用ngdoc 指令。还有一个有趣的链接：Writing AngularJS Documentation
@Brakebein :thanx，不幸的是，对于这个项目使用 JSDoc 是我老板必须的，他不希望我使用 ngdoc

标签： javascript angularjs jsdoc

【解决方案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
 */

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

/**
 * @namespace MyApp.Controllers
 */

【讨论】：

【解决方案2】：

虽然 JSDoc 确实有 @module，但它是一个“可见性”规范，我认为它不是您要寻找的。p>

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

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

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

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

@return {angular.Component} Component definition object.

希望有帮助！

【讨论】：