1 files changed, 13 insertions, 2 deletions
diff --git a/activemodel/lib/active_model/type/boolean.rb b/activemodel/lib/active_model/type/boolean.rb
index c1bce98c87..4e9d06a3ce 100644
--- a/activemodel/lib/active_model/type/boolean.rb
+++ b/activemodel/lib/active_model/type/boolean.rb
@@ -1,9 +1,20 @@
 module ActiveModel
   module Type
-    class Boolean < Value # :nodoc:
+    # == Active \Model \Type \Boolean
+    #
+    # A class that behaves like a boolean type, including rules for coercion of user input.
+    #
+    # === Coercion
+    # Values set from user input will first be coerced into the appropriate ruby type.
+    # Coercion behavior is roughly mapped to Ruby's boolean semantics.
+    #
+    # - "false", "f" , "0", +0+ or any other value in +FALSE_VALUES+ will be coerced to +false+
+    # - Empty strings are coerced to +nil+
+    # - All other values will be coerced to +true+
+    class Boolean < Value
       FALSE_VALUES = [false, 0, '0', 'f', 'F', 'false', 'FALSE', 'off', 'OFF'].to_set
 
-      def type
+      def type # :nodoc:
         :boolean
       end