From d2db3213608166c733e1bcf102fa9dee986f31d8 Mon Sep 17 00:00:00 2001 From: Sean Griffin Date: Fri, 6 Feb 2015 13:39:40 -0700 Subject: [PATCH] Grammar and RDoc formatting --- activerecord/lib/active_record/attributes.rb | 44 ++++++++++---------- activerecord/lib/active_record/type/value.rb | 28 ++++++------- 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