AngularJS服务中的JSDoc

Question

I'm creating an AngularJS service to validate form inputs and I can't for the life of me figure out how to use JSDoc3 to create reasonable documentation.

Ideally I need to export the documentation for the validator service as well as the documentation for each validator (internal objects)

After googling around a bit I was able to get it kind of working by hacking around a bit with namespaces, but I'm wondering if there's a right way to do this. A way that won't muck up somebody else's JSDoc if they include my service.

Example:

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.
        }
    };
}]);

In a perfect world, modifications to the above would let me generate a nice, non-global, JSDoc hierarchy where a user could read about how to use the validator as a whole, or dive in and look what needed to be passed in for each type of validation.

Thanks so much for any help you can give!

Answer 1

The way my team works is that we actually only document the actual factory function as if the user were going to read it. You've actually skipped over that guy. Either way, you can treat that as the entry point for your documentation and combine it with your "method" documentation for the full picture. You could make use of the @namespace documentation in combination with this.

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

Depending on what you really want, you may prefer to use a prototype. That's where documentation can really shine:

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

Using the prototype with your documentation really sticks it all together for me. It's like documenting your validator as one class entity, which makes the most sense to me.