Improved and corrected API docs

lib/validations.js

@@ -8,17 +8,14 @@ exports.ValidationError = ValidationError;
 exports.Validatable = Validatable;
 
 /**
- * Validation mixins for LoopBack models.
- *
  * This class provides methods that add validation cababilities to models.
- * Each of this validations run when `obj.isValid()` method called.
+ * Each of the validations runs when the `obj.isValid()` method is called.
  *
- * Each configurator can accept *n* params (*n*-1 field names and one config). Config
+ * All of the methods have an options object parameter that has a
- * is {Object} depends on specific validation, but all of them have a
+ * `message` property.  When there is only a single error message, this property is just a string;
- * `message` member property. It can be just string, when only one situation possible,
+ * for example: `Post.validatesPresenceOf('title', { message: 'can not be blank' });`
- * For example: `Post.validatesPresenceOf('title', { message: 'can not be blank' });`
  *
- * In more complicated cases it can be {Hash} of messages (for each case):
+ * In more complicated cases it can be a set of messages, for each possible error condition; for example:
  * `User.validatesLengthOf('password', { min: 6, max: 20, message: {min: 'too short', max: 'too long'}});`
  * @class Validatable
  */
@@ -85,7 +82,7 @@ Validatable.validatesAbsenceOf = getConfigurator('absence');
  * User.validatesLengthOf('state', {is: 2, message: {is: 'is not valid state name'}});
  * ```
  * @param {String} propertyName  Property name to validate.
- * @options {Object} Options
+ * @options {Object} Options See below.
  * @property {Number} is Value that property must equal to validate.
  * @property {Number} min Value that property must be less than to be valid.
  * @property {Number} max Value that property must be less than to be valid.
@@ -103,9 +100,10 @@ Validatable.validatesLengthOf = getConfigurator('length');
  * ```
  *
  * @param {String} propertyName  Property name to validate.
- * @options {Object} Options
+ * @options {Object} Options See below.
  * @property {Boolean} int If true, then property must be an integer to be valid.
  * @property {Object} message Optional object with string properties for 'int' for integer validation.  Default error messages:
+ *
  * - number: is not a number
  * - int: is not an integer
  */
@@ -124,7 +122,7 @@ Validatable.validatesNumericalityOf = getConfigurator('numericality');
  *
  * @param {String} propertyName  Property name to validate.
  * @options {Object} Options
- * @property {Array} in Array Property must match one of the values in the array to be valid.
+ * @property {Array} inArray Property must match one of the values in the array to be valid.
  * @property {String} message Optional error message if property is not valid.   Default error message: "is not included in the list".
  */
 Validatable.validatesInclusionOf = getConfigurator('inclusion');
@@ -136,7 +134,7 @@ Validatable.validatesInclusionOf = getConfigurator('inclusion');
  *
  * @param {String} propertyName  Property name to validate.
  * @options {Object} Options
- * @property {Array} in Array Property must match one of the values in the array to be valid.
+ * @property {Array} inArray Property must match one of the values in the array to be valid.
  * @property {String} message Optional error message if property is not valid.  Default error message: "is reserved".
  */
 Validatable.validatesExclusionOf = getConfigurator('exclusion');
@@ -155,9 +153,7 @@ Validatable.validatesExclusionOf = getConfigurator('exclusion');
 Validatable.validatesFormatOf = getConfigurator('format');
 
 /**
- * Validate using custom validator
+ * Validate using custom validation function.
- *
- * Default error message: is invalid
  *
  * Example:
  *
@@ -178,9 +174,8 @@ Validatable.validatesFormatOf = getConfigurator('format');
 Validatable.validate = getConfigurator('custom');
 
 /**
- * Validate using custom async validator
+ * Validate using custom asynchronous validation function.
  *
- * Default error message: is invalid
  *
  * Example:
  *```js
@@ -203,6 +198,7 @@ Validatable.validate = getConfigurator('custom');
  *     })
  *```
  * @param {String} propertyName  Property name to validate.
+ * @param {Function} validatorFn Custom validation function.
  * @options {Object} Options See below
  * @property {String} message Optional error message if property is not valid.  Default error message: " is invalid".
  */
@@ -225,7 +221,7 @@ Validatable.validateAsync = getConfigurator('custom', {async: true});
  * ```
 
  * @param {String} propertyName  Property name to validate.
- * @options {Object} Options
+ * @options {Object} Options See below.
  * @property {RegExp} with Regular expression to validate format.
  * @property {Array.<String>} scopedTo List of properties defining the scope.
  * @property {String} message Optional error message if property is not valid.  Default error message: "is not unique".
@@ -409,7 +405,7 @@ function getConfigurator(name, opts) {
  * });
  * ```
  * @param {Function} callback called with (valid)
- * @returns {Boolean} True if no asynchronouse validation is configured and all properties pass validation.
+ * @returns {Boolean} True if no asynchronous validation is configured and all properties pass validation.
  */
 Validatable.prototype.isValid = function (callback, data) {
   var valid = true, inst = this, wait = 0, async = false;