JSDoc与AngularJS的结合

Question

JSDoc与AngularJS的结合

34

目前在我的项目中我们正在使用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() 内容进行文档化，有什么建议吗？

- Nick White

2个回答

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);
})();

- Nick White

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- gm2008 · Accepted Answer

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

1.创建一个带有以下注释的空白.js文件：

 /**
  * @namespace angular_module
  */

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

2.在定义任何新的 Angular 模块的 JavaScript 文件中，请使用此类注释。

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

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

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”的实例方法。
Person.say // 名为“say”的静态方法。
Person~say // 名为“say”的内部方法。

然而，将控制器注释为类的一个不完美之处是，在生成的HTML文档中，将在控制器名称之前找到“new”，因为它被描述为类构造函数。

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

/**
 * @namespace MyApp.Controllers
 */

并将所有控制器的前缀更改为MyApp.Controllers。您还可以定义名称空间，例如MyApp.Product或MyApp.Customer等。

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

它很简单;
模块-控制器-函数层次结构得以保留;
它保持了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

就是这样。