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代碼：

詞根記憶一片空白。js文件有以下評論：

/** 
    * @namespace angular_module 
    */ 

這將爲上市產生的文檔中創建一個單獨的HTML所有模塊。

2.In定義任何新的角度模塊的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文件。點分隔的完整路徑字符串構建連接。

有三種語法的名路徑名：

• 人＃//說命名實例方法「之稱。」
• Person.say //名爲「say」的靜態方法。「
• 人〜//說叫內法‘說。’

然而，評論控制器作爲一個階級的一個不完美的一點是，‘新’將控制器名稱前生成的發現HTML文檔，因爲它被描述爲類構造函數。

此外，還可以以添加的分層結構定義的命名空間。例如，可以定義一個命名空間來包括所有的控制器

/** 
* @namespace MyApp.Controllers 
*/ 

，前綴爲MyApp.Controllers的所有控制器。你也可以這樣定義MyApp.Product或MyApp.Customer等命名空間

雖然並不完美，我喜歡用jsdoc記錄angularjs代碼，因爲

1. 它是簡單的;
2. 保留模塊控制器功能層次結構;
3. 它保持jsdoc的優點，它是一個可瀏覽的文檔站點。

表格樣式jsdoc樣式表：

特別，我已經適應了默認jsdoc樣式表像Java API文檔表樣式。它看起來更清楚。與此文件https://github.com/gm2008/jsdoc/blob/master/templates/default/static/styles/jsdoc-default.css

就是這樣C:\Users\user1\AppData\Roaming\npm\node_modules\jsdoc\templates\default\static\styles：

在Windows中，我替換此文件。

Answer 2

我不得不下去上述類型以外創建的功能和調用這些功能，在這樣的事情。運行或工廠等

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