Javascript AngularJS服务中的JSDoc

我正在创建一个AngularJS服务来验证表单输入，我一辈子都不知道如何使用JSDoc3来创建合理的文档

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

在谷歌上搜索了一段时间后，我通过对名称空间进行黑客攻击，使它能够正常工作，但我想知道是否有一种正确的方法可以做到这一点。如果别人的JSDoc包含我的服务，这是一种不会弄脏别人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层次结构，用户可以在其中阅读如何整体使用验证器，或者深入了解每种类型的验证需要传递什么

---

非常感谢你能给予的任何帮助

我的团队的工作方式是，我们实际上只记录实际的工厂功能，就好像用户要阅读它一样。你真的跳过了那个家伙。无论哪种方式，您都可以将其作为文档的入口点，并将其与您的“方法”文档结合起来，以获得完整的信息。您可以结合使用@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);

在你的文档中使用原型，对我来说真的很有用。这就像将验证器记录为一个类实体，这对我来说最有意义