Grammar and RDoc formatting

2 files changed, 37 insertions, 35 deletions

diff --git a/activerecord/lib/active_record/attributes.rb b/activerecord/lib/active_record/attributes.rb
index 53f54ebae9..bef6020d71 100644
--- a/activerecord/lib/active_record/attributes.rb
+++ b/activerecord/lib/active_record/attributes.rb
@@ -1,7 +1,9 @@
 module ActiveRecord
+  # See ActiveRecord::Attributes::ClassMethods for documentation
   module Attributes
     extend ActiveSupport::Concern
 
+    # :nodoc:
     Type = ActiveRecord::Type
 
     included do
@@ -14,7 +16,7 @@ module ActiveRecord
       # type of existing attributes if needed. This allows control over how
       # values are converted to and from SQL when assigned to a model. It also
       # changes the behavior of values passed to
-      # +ActiveRecord::Relation::QueryMethods#where+. This will let you use
+      # ActiveRecord::QueryMethods#where. This will let you use
       # your domain objects across much of Active Record, without having to
       # rely on implementation details or monkey patching.
       #
@@ -31,9 +33,9 @@ module ActiveRecord
       # is not passed, the previous default value (if any) will be used.
       # Otherwise, the default will be +nil+.
       #
-      # +array+ (PG only) specifies that the type should be an array (see the examples below)
+      # +array+ (PG only) specifies that the type should be an array (see the examples below).
       #
-      # +range+ (PG only) specifies that the type should be a range (see the examples below)
+      # +range+ (PG only) specifies that the type should be a range (see the examples below).
       #
       # ==== Examples
       #
@@ -84,19 +86,20 @@ module ActiveRecord
       # ==== Creating Custom Types
       #
       # Users may also define their own custom types, as long as they respond
-      # to the methods defined on the value type. The +type_cast+ method on
-      # your type object will be called with values both from the database, and
-      # from your controllers. See +ActiveRecord::Attributes::Type::Value+ for
-      # the expected API. It is recommended that your type objects inherit from
-      # an existing type, or the base value type.
+      # to the methods defined on the value type. The method
+      # +type_cast_from_database+ or +type_cast_from_user+ will be called on
+      # your type object, with raw input from the database or from your
+      # controllers.  See ActiveRecord::Type::Value for the expected API. It is
+      # recommended that your type objects inherit from an existing type, or
+      # from ActiveRecord::Type::Value
       #
       #   class MoneyType < ActiveRecord::Type::Integer
-      #     def type_cast(value)
+      #     def type_cast_from_user(value)
       #       if value.include?('$')
       #         price_in_dollars = value.gsub(/\$/, '').to_f
-      #         price_in_dollars * 100
+      #         super(price_in_dollars * 100)
       #       else
-      #         value.to_i
+      #         super
       #       end
       #     end
       #   end
@@ -109,11 +112,11 @@ module ActiveRecord
       #   store_listing.price_in_cents # => 1000
       #
       # For more details on creating custom types, see the documentation for
-      # +ActiveRecord::Type::Value+
+      # ActiveRecord::Type::Value
       #
       # ==== Querying
       #
-      # When +ActiveRecord::Relation::QueryMethods#where+ is called, it will
+      # When ActiveRecord::QueryMethods#where is called, it will
       # use the type defined by the model class to convert the value to SQL,
       # calling +type_cast_for_database+ on your type object. For example:
       #
@@ -149,9 +152,8 @@ module ActiveRecord
       #
       # The type of an attribute is given the opportunity to change how dirty
       # tracking is performed. The methods +changed?+ and +changed_in_place?+
-      # will be called from +ActiveRecord::AttributeMethods::Dirty+. See the
-      # documentation for those methods in +ActiveRecord::Type::Value+ for more
-      # details.
+      # will be called from ActiveModel::Dirty. See the documentation for those
+      # methods in ActiveRecord::Type::Value for more details.
       def attribute(name, cast_type, **options)
         name = name.to_s
         reload_schema_from_cache
@@ -165,20 +167,20 @@ module ActiveRecord
       # This is the low level API which sits beneath +attribute+. It only
       # accepts type objects, and will do its work immediately instead of
       # waiting for the schema to load. Automatic schema detection and
-      # +attribute+ both call this under the hood. While this method is
-      # provided so it can be used by plugin authors, application code should
-      # probably use +attribute+.
+      # ClassMethods#attribute both call this under the hood. While this method
+      # is provided so it can be used by plugin authors, application code
+      # should probably use ClassMethods#attribute.
       #
       # +name+ The name of the attribute being defined. Expected to be a +String+.
       #
-      # +cast_type+ The type object to use for this attribute
+      # +cast_type+ The type object to use for this attribute.
       #
       # +default+ The default value to use when no value is provided. If this option
       # is not passed, the previous default value (if any) will be used.
       # Otherwise, the default will be +nil+.
       #
       # +user_provided_default+ Whether the default value should be cast using
-      # +type_cast_from_user+ or +type_cast_from_database+
+      # +type_cast_from_user+ or +type_cast_from_database+.
       def define_attribute(
         name,
         cast_type,
diff --git a/activerecord/lib/active_record/type/value.rb b/activerecord/lib/active_record/type/value.rb
index 7f41d525e1..b800e33e6f 100644
--- a/activerecord/lib/active_record/type/value.rb
+++ b/activerecord/lib/active_record/type/value.rb
@@ -9,14 +9,15 @@ module ActiveRecord
         @limit = limit
       end
 
-      def type; end # :nodoc:
+      def type # :nodoc:
+      end
 
       # Convert a value from database input to the appropriate ruby type. The
       # return value of this method will be returned from
-      # +ActiveRecord::AttributeMethods::Read#read_attribute+. See also
-      # +type_cast+ and +cast_value+
+      # ActiveRecord::AttributeMethods::Read#read_attribute. See also
+      # Value#type_cast and Value#cast_value.
       #
-      # +value+ The raw input, as provided from the database
+      # +value+ The raw input, as provided from the database.
       def type_cast_from_database(value)
         type_cast(value)
       end
@@ -27,8 +28,8 @@ module ActiveRecord
       # from.
       #
       # The return value of this method will be returned from
-      # +ActiveRecord::AttributeMethods::Read#read_attribute+. See also:
-      # +type_cast+ and +cast_value+
+      # ActiveRecord::AttributeMethods::Read#read_attribute. See also:
+      # Value#type_cast and Value#cast_value.
       #
       # +value+ The raw input, as provided to the attribute setter.
       def type_cast_from_user(value)
@@ -38,7 +39,7 @@ module ActiveRecord
       # 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+
+      # +nil+.
       def type_cast_for_database(value)
         value
       end
@@ -78,12 +79,12 @@ module ActiveRecord
       # which could be mutated, you should override this method. You will need
       # to either:
       #
-      # - pass +new_value+ to +type_cast_for_database+ and compare it to
+      # - pass +new_value+ to Value#type_cast_for_database and compare it to
       #   +raw_old_value+
       #
       # or
       #
-      # - pass +raw_old_value+ to +type_cast_from_database+ and compare it to
+      # - pass +raw_old_value+ to Value#type_cast_from_database and compare it to
       #   +new_value+
       #
       # +raw_old_value+ The original value, before being passed to
@@ -104,17 +105,16 @@ module ActiveRecord
       private
 
       # Convenience method. If you don't need separate behavior for
-      # +type_cast_from_database+ and +type_cast_from_user+, you can override
+      # Value#type_cast_from_database and Value#type_cast_from_user, you can override
       # this method instead. The default behavior of both methods is to call
-      # this one. See also +cast_value+
+      # this one. See also Value#cast_value.
       def type_cast(value) # :doc:
         cast_value(value) unless value.nil?
       end
 
       # 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+.
+      # behavior for user and database inputs. Called by Value#type_cast for
+      # values except +nil+.
       def cast_value(value) # :doc:
         value
       end