diff --git a/lib/validatable.js b/lib/validatable.js
index ddccbb29..06f1ac71 100644
--- a/lib/validatable.js
+++ b/lib/validatable.js
@@ -134,6 +134,17 @@ Validatable.validatesFormatOf = getConfigurator('format');
  *
  * Default error message: is invalid
  *
+ * Example:
+ *
+ *     User.validate('name', customValidator, {message: 'Bad name'});
+ *     function customValidator(err) {
+ *         if (this.name === 'bad') err();
+ *     });
+ *     var user = new User({name: 'Peter'});
+ *     user.isValid(); // true
+ *     user.name = 'bad';
+ *     user.isValid(); // false
+ *
  * @nocode
  * @see helper/validateCustom
  */
@@ -144,6 +155,26 @@ Validatable.validate = getConfigurator('custom');
  *
  * Default error message: is invalid
  *
+ * Example:
+ *
+ *     User.validateAsync('name', customValidator, {message: 'Bad name'});
+ *     function customValidator(err, done) {
+ *         process.nextTick(function () {
+ *             if (this.name === 'bad') err();
+ *             done();
+ *         });
+ *     });
+ *     var user = new User({name: 'Peter'});
+ *     user.isValid(); // false (because async validation setup)
+ *     user.isValid(function (isValid) {
+ *         isValid; // true
+ *     })
+ *     user.name = 'bad';
+ *     user.isValid(); // false
+ *     user.isValid(function (isValid) {
+ *         isValid; // false
+ *     })
+ *
  * @async
  * @nocode
  * @see helper/validateCustom