javascript - AngularJS 服务中的 JSDoc

Question

我正在创建一个 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 层次结构，用户可以在其中阅读有关如何使用整个验证器的信息，或者深入了解需要传递的内容用于每种类型的验证。

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

Answer 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);

根据您真正想要的，您可能更喜欢使用原型(prototype)。这就是文档真正发挥作用的地方:

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

对我来说，将原型(prototype)与您的文档结合使用确实使它们融为一体。这就像将您的验证器记录为一个类实体，这对我来说最有意义。