docs, clarify the meanaing of return values from validation methods.

[ci skip]

Closes #20792.

Custom validation methods are implemented in terms of
callbacks. The `validate` callback chain can't be halted using return
values of individual callbacks.

2 files changed, 6 insertions, 2 deletions

diff --git a/activemodel/lib/active_model/validations.rb b/activemodel/lib/active_model/validations.rb
index 4f4c75d165..72094a26c0 100644
--- a/activemodel/lib/active_model/validations.rb
+++ b/activemodel/lib/active_model/validations.rb
@@ -129,6 +129,9 @@ module ActiveModel
       #     end
       #   end
       #
+      # Note that the return value of validation methods is not relevant.
+      # It's not possible to halt the validate callback chain.
+      #
       # Options:
       # * <tt>:on</tt> - Specifies the contexts where this validation is active.
       #   Runs in all validation contexts by default (nil). You can pass a symbol
diff --git a/guides/source/active_record_validations.md b/guides/source/active_record_validations.md
index 7932853c11..71ca7a0f66 100644
--- a/guides/source/active_record_validations.md
+++ b/guides/source/active_record_validations.md
@@ -965,8 +965,9 @@ own custom validators.
 
 You can also create methods that verify the state of your models and add
 messages to the `errors` collection when they are invalid. You must then
-register these methods by using the `validate` class method, passing in the
-symbols for the validation methods' names.
+register these methods by using the `validate`
+([API](http://api.rubyonrails.org/classes/ActiveModel/Validations/ClassMethods.html#method-i-validate))
+class method, passing in the symbols for the validation methods' names.
 
 You can pass more than one symbol for each class method and the respective
 validations will be run in the same order as they were registered.