Merge docrails

3 files changed, 116 insertions, 48 deletions

diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
index 75032efe57..22304edfc9 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
@@ -252,6 +252,10 @@ module ActiveRecord
     class IndexDefinition < Struct.new(:table, :name, :unique, :columns) #:nodoc:
     end
 
+    # Abstract representation of a column definition. Instances of this type
+    # are typically created by methods in TableDefinition, and added to the
+    # +columns+ attribute of said TableDefinition object, in order to be used
+    # for generating a number of table creation or table changing SQL statements.
     class ColumnDefinition < Struct.new(:base, :name, :type, :limit, :precision, :scale, :default, :null) #:nodoc:
 
       def sql_type
@@ -275,9 +279,29 @@ module ActiveRecord
         end
     end
 
-    # Represents a SQL table in an abstract way.
-    # Columns are stored as a ColumnDefinition in the +columns+ attribute.
+    # Represents the schema of an SQL table in an abstract way. This class
+    # provides methods for manipulating the schema representation.
+    #
+    # Inside migration files, the +t+ object in +create_table+ and
+    # +change_table+ is actually of this type:
+    #
+    #   class SomeMigration < ActiveRecord::Migration
+    #     def self.up
+    #       create_table :foo do |t|
+    #         puts t.class  # => "ActiveRecord::ConnectionAdapters::TableDefinition"
+    #       end
+    #     end
+    #     
+    #     def self.down
+    #       ...
+    #     end
+    #   end
+    #
+    # The table definitions
+    # The Columns are stored as a ColumnDefinition in the +columns+ attribute.
     class TableDefinition
+      # An array of ColumnDefinition objects, representing the column changes
+      # that have been defined.
       attr_accessor :columns
 
       def initialize(base)
@@ -321,6 +345,12 @@ module ActiveRecord
       # * <tt>:scale</tt> -
       #   Specifies the scale for a <tt>:decimal</tt> column.
       #
+      # For clarity's sake: the precision is the number of significant digits,
+      # while the scale is the number of digits that can be stored following
+      # the decimal point. For example, the number 123.45 has a precision of 5
+      # and a scale of 2. A decimal with a precision of 5 and a scale of 2 can
+      # range from -999.99 to 999.99.
+      #
       # Please be aware of different RDBMS implementations behavior with
       # <tt>:decimal</tt> columns:
       # * The SQL standard says the default scale should be 0, <tt>:scale</tt> <=
@@ -374,6 +404,10 @@ module ActiveRecord
       #  td.column(:huge_integer, :decimal, :precision => 30)
       #  # => huge_integer DECIMAL(30)
       #
+      #  # Defines a column with a database-specific type.
+      #  td.column(:foo, 'polygon')
+      #  # => foo polygon
+      #
       # == Short-hand examples
       #
       # Instead of calling +column+ directly, you can also work with the short-hand definitions for the default types.
diff --git a/activerecord/lib/active_record/locale/en-US.yml b/activerecord/lib/active_record/locale/en-US.yml
index 8148f31a81..421f0ebd60 100644
--- a/activerecord/lib/active_record/locale/en-US.yml
+++ b/activerecord/lib/active_record/locale/en-US.yml
@@ -25,9 +25,30 @@ en-US:
         even: "must be even"
         # Append your own errors here or at the model/attributes scope.
 
+      # You can define own errors for models or model attributes.
+      # The values :model, :attribute and :value are always available for interpolation.
+      #
+      # For example,
+      #   models:
+      #     user:
+      #       blank: "This is a custom blank message for {{model}}: {{attribute}}"
+      #       attributes:
+      #         login:
+      #           blank: "This is a custom blank message for User login"
+      # Will define custom blank validation message for User model and 
+      # custom blank validation message for login attribute of User model.
       models:
-        # Overrides default messages
-      
-      attributes:
-        # Overrides model and default messages.
+        
+    # Translate model names. Used in Model.human_name().
+    #models:
+      # For example,
+      #   user: "Dude"
+      # will translate User model name to "Dude"
+    
+    # Translate model attribute names. Used in Model.human_attribute_name(attribute).
+    #attributes:
+      # For example,
+      #   user:
+      #     login: "Handle"
+      # will translate User attribute "login" as "Handle"
 
diff --git a/activerecord/lib/active_record/validations.rb b/activerecord/lib/active_record/validations.rb
index 577e30ec86..518b59e433 100644
--- a/activerecord/lib/active_record/validations.rb
+++ b/activerecord/lib/active_record/validations.rb
@@ -259,6 +259,8 @@ module ActiveRecord
   end
 
 
+  # Please do have a look at ActiveRecord::Validations::ClassMethods for a higher level of validations.
+  #
   # Active Records implement validation by overwriting Base#validate (or the variations, +validate_on_create+ and
   # +validate_on_update+). Each of these methods can inspect the state of the object, which usually means ensuring
   # that a number of attributes have a certain value (such as not empty, within a given range, matching a certain regular expression).
@@ -297,8 +299,6 @@ module ActiveRecord
   #   person.save # => true (and person is now saved in the database)
   #
   # An Errors object is automatically created for every Active Record.
-  #
-  # Please do have a look at ActiveRecord::Validations::ClassMethods for a higher level of validations.
   module Validations
     VALIDATIONS = %w( validate validate_on_create validate_on_update )
 
@@ -313,9 +313,50 @@ module ActiveRecord
       base.define_callbacks *VALIDATIONS
     end
 
-    # All of the following validations are defined in the class scope of the model that you're interested in validating.
-    # They offer a more declarative way of specifying when the model is valid and when it is not. It is recommended to use
-    # these over the low-level calls to +validate+ and +validate_on_create+ when possible.
+    # Active Record classes can implement validations in several ways. The highest level, easiest to read,
+    # and recommended approach is to use the declarative <tt>validates_..._of</tt> class methods (and
+    # +validates_associated+) documented below. These are sufficient for most model validations.
+    #
+    # Slightly lower level is +validates_each+. It provides some of the same options as the purely declarative
+    # validation methods, but like all the lower-level approaches it requires manually adding to the errors collection
+    # when the record is invalid.
+    #
+    # At a yet lower level, a model can use the class methods +validate+, +validate_on_create+ and +validate_on_update+
+    # to add validation methods or blocks. These are ActiveSupport::Callbacks and follow the same rules of inheritance
+    # and chaining.
+    #
+    # The lowest level style is to define the instance methods +validate+, +validate_on_create+ and +validate_on_update+
+    # as documented in ActiveRecord::Validations.
+    #
+    # == +validate+, +validate_on_create+ and +validate_on_update+ Class Methods
+    #
+    # Calls to these methods add a validation method or block to the class. Again, this approach is recommended
+    # only when the higher-level methods documented below (<tt>validates_..._of</tt> and +validates_associated+) are
+    # insufficient to handle the required validation.
+    #
+    # This can be done with a symbol pointing to a method:
+    #
+    #   class Comment < ActiveRecord::Base
+    #     validate :must_be_friends
+    #
+    #     def must_be_friends
+    #       errors.add_to_base("Must be friends to leave a comment") unless commenter.friend_of?(commentee)
+    #     end
+    #   end
+    #
+    # Or with a block which is passed the current record to be validated:
+    #
+    #   class Comment < ActiveRecord::Base
+    #     validate do |comment|
+    #       comment.must_be_friends
+    #     end
+    #
+    #     def must_be_friends
+    #       errors.add_to_base("Must be friends to leave a comment") unless commenter.friend_of?(commentee)
+    #     end
+    #   end
+    #
+    # This usage applies to +validate_on_create+ and +validate_on_update+ as well.
     module ClassMethods
       DEFAULT_VALIDATION_OPTIONS = {
         :on => :save,
@@ -329,34 +370,6 @@ module ActiveRecord
                                   :equal_to => '==', :less_than => '<', :less_than_or_equal_to => '<=',
                                   :odd => 'odd?', :even => 'even?' }.freeze
 
-      # Adds a validation method or block to the class. This is useful when
-      # overriding the +validate+ instance method becomes too unwieldy and
-      # you're looking for more descriptive declaration of your validations.
-      #
-      # This can be done with a symbol pointing to a method:
-      #
-      #   class Comment < ActiveRecord::Base
-      #     validate :must_be_friends
-      #
-      #     def must_be_friends
-      #       errors.add_to_base("Must be friends to leave a comment") unless commenter.friend_of?(commentee)
-      #     end
-      #   end
-      #
-      # Or with a block which is passed the current record to be validated:
-      #
-      #   class Comment < ActiveRecord::Base
-      #     validate do |comment|
-      #       comment.must_be_friends
-      #     end
-      #
-      #     def must_be_friends
-      #       errors.add_to_base("Must be friends to leave a comment") unless commenter.friend_of?(commentee)
-      #     end
-      #   end
-      #
-      # This usage applies to +validate_on_create+ and +validate_on_update+ as well.
-
       # Validates each attribute against a block.
       #
       #   class Person < ActiveRecord::Base
@@ -509,13 +522,13 @@ module ActiveRecord
       #
       #   class Person < ActiveRecord::Base
       #     validates_length_of :first_name, :maximum=>30
-      #     validates_length_of :last_name, :maximum=>30, :message=>"less than %d if you don't mind"
+      #     validates_length_of :last_name, :maximum=>30, :message=>"less than {{count}} if you don't mind"
       #     validates_length_of :fax, :in => 7..32, :allow_nil => true
       #     validates_length_of :phone, :in => 7..32, :allow_blank => true
       #     validates_length_of :user_name, :within => 6..20, :too_long => "pick a shorter name", :too_short => "pick a longer name"
-      #     validates_length_of :fav_bra_size, :minimum => 1, :too_short => "please enter at least %d character"
-      #     validates_length_of :smurf_leader, :is => 4, :message => "papa is spelled with %d characters... don't play me."
-      #     validates_length_of :essay, :minimum => 100, :too_short => "Your essay must be at least %d words."), :tokenizer => lambda {|str| str.scan(/\w+/) }
+      #     validates_length_of :fav_bra_size, :minimum => 1, :too_short => "please enter at least {{count}} character"
+      #     validates_length_of :smurf_leader, :is => 4, :message => "papa is spelled with {{count}} characters... don't play me."
+      #     validates_length_of :essay, :minimum => 100, :too_short => "Your essay must be at least {{count}} words."), :tokenizer => lambda {|str| str.scan(/\w+/) }
       #   end
       #
       # Configuration options:
@@ -526,9 +539,9 @@ module ActiveRecord
       # * <tt>:in</tt> - A synonym(or alias) for <tt>:within</tt>.
       # * <tt>:allow_nil</tt> - Attribute may be +nil+; skip validation.
       # * <tt>:allow_blank</tt> - Attribute may be blank; skip validation.
-      # * <tt>:too_long</tt> - The error message if the attribute goes over the maximum (default is: "is too long (maximum is %d characters)").
-      # * <tt>:too_short</tt> - The error message if the attribute goes under the minimum (default is: "is too short (min is %d characters)").
-      # * <tt>:wrong_length</tt> - The error message if using the <tt>:is</tt> method and the attribute is the wrong size (default is: "is the wrong length (should be %d characters)").
+      # * <tt>:too_long</tt> - The error message if the attribute goes over the maximum (default is: "is too long (maximum is {{count}} characters)").
+      # * <tt>:too_short</tt> - The error message if the attribute goes under the minimum (default is: "is too short (min is {{count}} characters)").
+      # * <tt>:wrong_length</tt> - The error message if using the <tt>:is</tt> method and the attribute is the wrong size (default is: "is the wrong length (should be {{count}} characters)").
       # * <tt>:message</tt> - The error message to use for a <tt>:minimum</tt>, <tt>:maximum</tt>, or <tt>:is</tt> violation.  An alias of the appropriate <tt>too_long</tt>/<tt>too_short</tt>/<tt>wrong_length</tt> message.
       # * <tt>:on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>).
       # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
@@ -731,7 +744,7 @@ module ActiveRecord
       #   class Person < ActiveRecord::Base
       #     validates_inclusion_of :gender, :in => %w( m f ), :message => "woah! what are you then!??!!"
       #     validates_inclusion_of :age, :in => 0..99
-      #     validates_inclusion_of :format, :in => %w( jpg gif png ), :message => "extension %s is not included in the list"
+      #     validates_inclusion_of :format, :in => %w( jpg gif png ), :message => "extension {{value}} is not included in the list"
       #   end
       #
       # Configuration options:
@@ -765,7 +778,7 @@ module ActiveRecord
       #   class Person < ActiveRecord::Base
       #     validates_exclusion_of :username, :in => %w( admin superuser ), :message => "You don't belong here"
       #     validates_exclusion_of :age, :in => 30..60, :message => "This site is only for under 30 and over 60"
-      #     validates_exclusion_of :format, :in => %w( mov avi ), :message => "extension %s is not allowed"
+      #     validates_exclusion_of :format, :in => %w( mov avi ), :message => "extension {{value}} is not allowed"
       #   end
       #
       # Configuration options: