From 67babb81da5f6d7de80f1086cc3ca9a8dab6efe1 Mon Sep 17 00:00:00 2001
From: Valeri Karpov <val@karpov.io>
Date: Thu, 21 Nov 2019 08:54:04 -0800
Subject: [PATCH] docs(error): add more detail about the ValidatorError class,
 including properties

Fix #8346
---
 lib/error/index.js | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/lib/error/index.js b/lib/error/index.js
index 38c4d6cacb2..ec4188d61c9 100644
--- a/lib/error/index.js
+++ b/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