4 files changed, 48 insertions, 28 deletions

diff --git a/activerecord/lib/active_record/type/binary.rb b/activerecord/lib/active_record/type/binary.rb
index 3bf29b5026..7416c554c7 100644
--- a/activerecord/lib/active_record/type/binary.rb
+++ b/activerecord/lib/active_record/type/binary.rb
@@ -22,7 +22,7 @@ module ActiveRecord
         Data.new(super)
       end
 
-      class Data
+      class Data # :nodoc:
         def initialize(value)
           @value = value
         end
diff --git a/activerecord/lib/active_record/type/mutable.rb b/activerecord/lib/active_record/type/mutable.rb
index 64cf4b9b93..066617ea59 100644
--- a/activerecord/lib/active_record/type/mutable.rb
+++ b/activerecord/lib/active_record/type/mutable.rb
@@ -1,6 +1,6 @@
 module ActiveRecord
   module Type
-    module Mutable
+    module Mutable # :nodoc:
       def type_cast_from_user(value)
         type_cast_from_database(type_cast_for_database(value))
       end
@@ -8,7 +8,7 @@ module ActiveRecord
       # +raw_old_value+ will be the `_before_type_cast` version of the
       # value (likely a string). +new_value+ will be the current, type
       # cast value.
-      def changed_in_place?(raw_old_value, new_value) # :nodoc:
+      def changed_in_place?(raw_old_value, new_value)
         raw_old_value != type_cast_for_database(new_value)
       end
     end
diff --git a/activerecord/lib/active_record/type/numeric.rb b/activerecord/lib/active_record/type/numeric.rb
index a7bf0657b9..fa43266504 100644
--- a/activerecord/lib/active_record/type/numeric.rb
+++ b/activerecord/lib/active_record/type/numeric.rb
@@ -16,13 +16,13 @@ module ActiveRecord
       end
 
       def changed?(old_value, _new_value, new_value_before_type_cast) # :nodoc:
-        super || zero_to_non_number?(old_value, new_value_before_type_cast)
+        super || number_to_non_number?(old_value, new_value_before_type_cast)
       end
 
       private
 
-      def zero_to_non_number?(old_value, new_value_before_type_cast)
-        old_value == 0 && non_numeric_string?(new_value_before_type_cast)
+      def number_to_non_number?(old_value, new_value_before_type_cast)
+        old_value != nil && non_numeric_string?(new_value_before_type_cast)
       end
 
       def non_numeric_string?(value)
diff --git a/activerecord/lib/active_record/type/value.rb b/activerecord/lib/active_record/type/value.rb
index 875fb98c4b..081da7547e 100644
--- a/activerecord/lib/active_record/type/value.rb
+++ b/activerecord/lib/active_record/type/value.rb
@@ -3,8 +3,8 @@ module ActiveRecord
     class Value # :nodoc:
       attr_reader :precision, :scale, :limit
 
-      # Valid options are +precision+, +scale+, and +limit+.
-      # They are only used when dumping schema.
+      # Valid options are +precision+, +scale+, and +limit+. They are only
+      # used when dumping schema.
       def initialize(options = {})
         options.assert_valid_keys(:precision, :scale, :limit)
         @precision = options[:precision]
@@ -12,65 +12,85 @@ module ActiveRecord
         @limit = options[:limit]
       end
 
-      # The simplified type that this object represents. Subclasses
-      # must override this method.
+      # The simplified type that this object represents. Returns a symbol such
+      # as +:string+ or +:integer+
       def type; end
 
+      # Type casts a string from the database into the appropriate ruby type.
+      # Classes which do not need separate type casting behavior for database
+      # and user provided values should override +cast_value+ instead.
       def type_cast_from_database(value)
         type_cast(value)
       end
 
+      # Type casts a value from user input (e.g. from a setter). This value may
+      # be a string from the form builder, or an already type cast value
+      # provided manually to a setter.
+      #
+      # Classes which do not need separate type casting behavior for database
+      # and user provided values should override +type_cast+ or +cast_value+
+      # instead.
       def type_cast_from_user(value)
         type_cast(value)
       end
 
+      # Cast a value from the ruby type to a type that the database knows how
+      # to understand. The returned value from this method should be a
+      # +String+, +Numeric+, +Date+, +Time+, +Symbol+, +true+, +false+, or
+      # +nil+
       def type_cast_for_database(value)
         value
       end
 
-      def type_cast_for_schema(value)
+      # Type cast a value for schema dumping. This method is private, as we are
+      # hoping to remove it entirely.
+      def type_cast_for_schema(value) # :nodoc:
         value.inspect
       end
 
-      def text?
+      # These predicates are not documented, as I need to look further into
+      # their use, and see if they can be removed entirely.
+      def text? # :nodoc:
         false
       end
 
-      def number?
+      def number? # :nodoc:
         false
       end
 
-      def binary?
+      def binary? # :nodoc:
         false
       end
 
       def klass # :nodoc:
       end
 
-      # +old_value+ will always be type-cast.
-      # +new_value+ will come straight from the database
-      # or from assignment, so it could be anything. Types
-      # which cannot typecast arbitrary values should override
-      # this method.
-      def changed?(old_value, new_value, _new_value_before_type_cast) # :nodoc:
+      # Determines whether a value has changed for dirty checking. +old_value+
+      # and +new_value+ will always be type-cast. Types should not need to
+      # override this method.
+      def changed?(old_value, new_value, _new_value_before_type_cast)
         old_value != new_value
       end
 
-      def changed_in_place?(*) # :nodoc:
+      # Determines whether the mutable value has been modified since it was
+      # read. Returns +false+ by default. This method should not need to be
+      # overriden directly. Types which return a mutable value should include
+      # +Type::Mutable+, which will define this method.
+      def changed_in_place?(*)
         false
       end
 
       private
-      # Takes an input from the database, or from attribute setters,
-      # and casts it to a type appropriate for this object. This method
-      # should not be overriden by subclasses. Instead, override `cast_value`.
-      def type_cast(value) # :api: public
+
+      def type_cast(value)
         cast_value(value) unless value.nil?
       end
 
-      # Responsible for casting values from external sources to the appropriate
-      # type. Called by `type_cast` for all values except `nil`.
-      def cast_value(value) # :api: public
+      # Convenience method for types which do not need separate type casting
+      # behavior for user and database inputs. Called by
+      # `type_cast_from_database` and `type_cast_from_user` for all values
+      # except `nil`.
+      def cast_value(value) # :doc:
         value
       end
     end