33

目前在我的项目中我们正在使用 JSDoc，我们最近开始实施 Angular，我想继续使用 JSDoc 以确保所有文档都在同一个地方。

我看过人们主要只是说要使用 ngDoc，但这并不是一个真正可行的选择，因为我们将始终拥有单独的 JavaScript，理想情况下我会将所有东西放在一起。

/**
 * @author Example <jon.doe@example.com>
 * @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() 提供任何想法的文档？

4

2 回答 2

68

我也遇到过这个问题。我现在正在通过这样的 jsdoc 注释为 angularjs 代码编写文档：

1.使用以下注释制作一个空白 .js 文件：

 /**
  * @namespace angular_module
  */

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

2.在定义任何新的角度模块的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.ProductorMyApp.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

就是这样。

于 2014-06-13T15:21:51.760 回答
5

我不得不沿着创建上述类型之外的函数并在 .run 或工厂等中调用这些函数的路线。

/**
 * @author Example <jon.doe@example.com>
 * @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;
    /**
     * My example bootstrap run function
     * @param  {object} $http    {@link http://docs.angularjs.org/api/ng.$http}
     * @param  {[type]} $cookies {@link http://docs.angularjs.org/api/ngCookies.$cookies}
     */
    var runFunction = function ($http, $cookies) {
        $http.defaults.headers.post['X-CSRFToken'] = $cookies.csrftoken;
        $http.defaults.headers.common['X-CSRFToken'] = $cookies.csrftoken;
    };

    /**
     * A Example Angular Bootstrap Module
     * @memberOf example.angular
     * @namespace example.angular.bootstrap
     * @function bootstrap
     * @example
     *     &lt;div ng-app="exampleAngularBootstrap"&gt;
     *         &lt;div ng-view&gt;&lt;/div&gt;
     *     &lt;/div&gt;  
     */
    exAngular.bootstrap = angular.module('exampleAngularBootstrap', [
            'ngRoute',
            'ngResource',
            'ngCookies'
        ])
        .run(runFunction);
})();
于 2014-01-29T10:32:29.020 回答