docs(error): add more detail about the ValidatorError class, includin…

…g properties

Fix #8346

lib/error/index.js

@@ -102,7 +102,32 @@ MongooseError.CastError = require('./cast');
 MongooseError.ValidationError = require('./validation');
 
 /**
- * A `ValidationError` has a hash of `errors` that contain individual `ValidatorError` instances
+ * A `ValidationError` has a hash of `errors` that contain individual
+ * `ValidatorError` instances.
+ *
+ * ####Example:
+ *
+ *     const schema = Schema({ name: { type: String, required: true } });
+ *     const Model = mongoose.model('Test', schema);
+ *     const doc = new Model({});
+ *
+ *     // Top-level error is a ValidationError, **not** a ValidatorError
+ *     const err = doc.validateSync();
+ *     err instanceof mongoose.Error.ValidationError; // true
+ *
+ *     // A ValidationError `err` has 0 or more ValidatorErrors keyed by the
+ *     // path in the `err.errors` property.
+ *     err.errors['name'] instanceof mongoose.Error.ValidatorError;
+ *
+ *     err.errors['name'].kind; // 'required'
+ *     err.errors['name'].path; // 'name'
+ *     err.errors['name'].value; // undefined
+ *
+ * Instances of `ValidatorError` have the following properties:
+ *
+ * - `kind`: The validator's `type`, like `'required'` or `'regexp'`
+ * - `path`: The path that failed validation
+ * - `value`: The value that failed validation
  *
  * @api public
  * @memberOf Error