Doc pass for `Type::Value` [ci skip]

2 files changed, 43 insertions, 23 deletions

diff --git a/activerecord/lib/active_record/type/mutable.rb b/activerecord/lib/active_record/type/mutable.rb
index 2c69f98a2d..066617ea59 100644
--- a/activerecord/lib/active_record/type/mutable.rb
+++ b/activerecord/lib/active_record/type/mutable.rb
@@ -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/value.rb b/activerecord/lib/active_record/type/value.rb
index 063139e620..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 overridden 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