AngularJS服務中的JSDoc

我正在創建一個AngularJS服務來驗證表單輸入，而且我不能爲我的生活弄清楚如何使用JSDoc3來創建合理的文檔。AngularJS服務中的JSDoc

理想我需要導出爲驗證服務的文檔以及爲每個校驗文件（內部對象）

google搜索了一下週圍，我能夠得到它的周圍有點黑客樣的工作後與命名空間，但我想知道是否有一個權利方式來做到這一點。如果他們包含我的服務，那麼這種方法不會將其他人的JSDoc弄糟。

例子：

angular.module('services.utility') 
.factory('validator', [function() { 
    var validators = { 
     /** 
     * Requires a field to have something in it. 
     * @param {String|Boolean} val The value to be checked. 
     * @return {Object} 
     */ 
     'required': function(val){ 
      // check against validator 
      return {'valid': true, 'msg': 'passed!'}; 
     }, 
     /** 
     * Requires a field to be less than a number. 
     * @param {Number} val The value to be checked. 
     * @param {Number} check The value to be checked against. 
     * @return {Object} 
     */ 
     'lessThan': function(val){ 
      // check against validator 
      return {'valid': true, 'msg': 'passed!'}; 
     } 
    }; 
    return { 
     /** 
     * This is the main validation routine. 
     * @param {Object} vObjs An object to be processed. 
     * @return {Boolean} 
     */ 
     'validate': function(thingsToValidate){ 
      // run some validations from the validators 
        // and return a bool. 
     } 
    }; 
}]);

在一個完美的世界，修改上述會讓我產生一個很好的，非全局，JSDoc層級結構，其中用戶可以瞭解如何使用驗證器作爲一個整體，或潛入並看看需要通過什麼類型的驗證。

非常感謝您的幫助！

來源

2012-12-07 betaorbust

我的團隊工作的方式是我們實際上只記錄實際的工廠功能，就好像用戶要閱讀它一樣。你實際上跳過那個人。無論採用哪種方式，您都可以將其作爲文檔的入口點，並將其與「方法」文檔結合起來，形成完整的畫面。您可以結合使用@namespace文檔。

/** Here is how you use my factory. @param @return */ 
my.validator.factory = function() { return { validate: function(){} }; } 
/** Here are some validators. @enum {Function(*):ValidationResult} **/ 
my.validator.Validators = {} 

module.factory('validator', my.validator.factory);

取決於你真正想，你可能更願意使用一個原型。這就是文檔可以真正發揮作用的地方：

/** Here is how you use my factory. @param @return @constructor */ 
my.Validator = function() {} 
/** My validation function. @param @return */ 
my.Validator.prototype.validate = function() {} 
/** Here are some validators. @enum {Function(*):ValidationResult} **/ 
my.Validator.Validators = {} 

module.service('validator', my.Validator);

在您的文檔中使用原型確實爲我一直使用它。這就像將您的驗證器記錄爲一個類實體，這對我最有意義。

來源

2013-01-22 01:56:40

AngularJS服務中的JSDoc

回答

相關問題