4

我正在创建一个 AngularJS 服务来验证表单输入，但我一生都无法弄清楚如何使用 JSDoc3 来创建合理的文档。

理想情况下，我需要导出验证器服务的文档以及每个验证器的文档（内部对象）

在谷歌搜索了一下之后，我能够通过使用命名空间来破解它，但我想知道是否有正确的方法来做到这一点。如果他们包含我的服务，则不会破坏其他人的 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 层次结构，用户可以在其中阅读有关如何使用整个验证器的信息，或者深入了解每个需要传递的内容验证类型。

非常感谢您提供的任何帮助！

4

1 回答 1

1

我的团队的工作方式是我们实际上只记录实际的工厂功能，就好像用户要阅读它一样。你实际上已经跳过了那个人。无论哪种方式，您都可以将其视为文档的入口点，并将其与您的“方法”文档结合起来以获得完整的图片。您可以结合使用@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-22T01:56:40.660 回答