带有AngularJS的JSDoc

Question

当前，在我的项目中，我们正在使用JSDoc，我们最近开始实现Angular，并且我想继续使用JSDoc，以确保所有文档都位于同一位置。

我看过的人主要是说要使用ngDoc，但这并不是一个切实可行的选择，因为我们将始终使用单独的JavaScript，并且理想情况下，我会将所有内容整合在一起。

/**
 * @author Example <[e-mail]>
 * @copyright 2014 Example Ltd. All rights reserved.
 */
(function () {
    window.example = window.example || {};
    /**
     * Example Namespace
     * @memberOf example
     * @namespace example.angular
     */
    window.example.angular = window.example.angular || {};
    var exAngular = window.example.angular;

    /**
     * A Example Angular Bootstrap Module
     * @module exampleAngularBootstrap
     */
    exAngular.bootstrap = angular.module('exampleAngularBootstrap', [
            'ngRoute',
            'ngResource',
            'ngCookies'
        ])
        .run(function ($http, $cookies) {
            $http.defaults.headers.post['X-CSRFToken'] = $cookies.csrftoken;
            $http.defaults.headers.common['X-CSRFToken'] = $cookies.csrftoken;
        });
})();

目前，这是我所拥有的，但是无法为run（）的文档添加任何想法？

Answer 1

我也遇到了这个问题。我现在正在通过jsdoc注释编写有关angularjs代码的文档，如下所示：

1.制作一个空白的.js文件并添加以下注释：

 /**
  * @namespace angular_module
  */

这将在生成的文档中创建一个单独的html，以列出所有模块。

2.在定义任何新的angular模块的javascript文件中，请使用这种注释

 /**
  * @class angular_module.MyModule
  * @memberOf angular_module    
  */

这将在上面所有angular_modules列表中添加一个项目，并为MyModule创建单独的html页面，因为它是一个类。

3.对于每个angularjs服务，请使用以下注释：

 /**
  * @function myService
  * @memberOf angular_module.MyModule
  * @description This is an angularjs service.
  */

这将在服务的MyModule页面中添加一个项目。因为它是作为函数添加的，所以您可以使用’@param’编写输入参数的文档，并使用’@return’编写返回值。

4.如果我在MyModule的控制器或指令中有很长的代码，并且想要有一个单独的html文件来对其进行文档记录，我将使用完整路径将控制器或指令注释为类。例如

 /**
  * @class angular_module.MyModule.MyController
  */

这样，MyController将作为MyModule的文档页面中的一项列出。

然后，我们可以将控制器中的代码注释为MyController的成员函数。

 /**
  * @name $scope.aScopeFunction
  * @function
  * @memberOf angular_module.MyModule.MyController
  * @description
  */

这样，此函数的文档将出现在MyController的html页面的html文件中。以句点分隔的完整路径字符串将建立连接。

名称路径有三种语法：

• Person＃say //名为“ say”的实例方法。
• Person.say //名为“ say”的静态方法。
• Person〜say //内部方法名为“ say”。

但是，将控制器注释为类的一个不完善之处是，在生成的html文档中，在控制器名称之前会找到一个“新”字符，因为它被描述为类构造函数。

1. 此外，您可以定义名称空间以添加层次结构。例如，您可以定义一个名称空间以包括所有控制器

   /**
   

   • @namespace MyApp.Controllers
     */
     

，并为所有控制器加上前缀MyApp.Controllers。您也可以定义名称空间，例如MyApp.Product或MyApp.Customer等。

虽然不完美，但我喜欢使用jsdoc来记录angularjs代码，因为

1. 很简单;
2. 保留模块控制器功能层次结构；
3. 并保留jsdoc的优点，即它是可浏览的文档站点。

表格样式jsdoc样式表：

特别是，我已经将默认的jsdoc样式表调整为类似于Java API文档的表格样式。看起来更清楚了。

在Windows中，我替换此文件：C:\Users\user1\AppData\Roaming\npm\node_modules\jsdoc\templates\default\static\styles这个文件https://github.com/gm2008/jsdoc/blob/master/templates/default/static/styles/jsdoc-
default.css

而已。