JSDoc与AngularJS

Question

目前在我的项目中我们使用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()提供任何想法的文档？

Answer 1

我也遇到过这个问题.我现在通过像这样的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文件中.以点分隔的完整路径字符串构建连接.

namepath有三种类型的语法:

• 人#说//名为"说"的实例方法.
• Person.say //名为"say"的静态方法.
• 人〜说//内部方法名为"说".

但是,将控制器注释为类的一个不完美之处在于,在生成的html文档中的控制器名称之前将找到"new",因为它被描述为类构造函数.

5. 此外,您可以定义名称空间以添加分层结构.例如,您可以定义名称空间以包含所有控制器

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

而已.

Answer 2

我不得不沿着在上述类型之外创建函数并在 .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);
})();