Merge branch 'master' of github.com:lifo/docrails

20 files changed, 258 insertions, 176 deletions

diff --git a/actionpack/lib/action_controller/metal/streaming.rb b/actionpack/lib/action_controller/metal/streaming.rb
index eeb37db2e7..9f3c997024 100644
--- a/actionpack/lib/action_controller/metal/streaming.rb
+++ b/actionpack/lib/action_controller/metal/streaming.rb
@@ -139,9 +139,6 @@ module ActionController #:nodoc:
   # session or flash after the template starts rendering will not propagate
   # to the client.
   #
-  # If you try to modify cookies, session or flash, an <tt>ActionDispatch::ClosedError</tt>
-  # will be raised, showing those objects are closed for modification.
-  #
   # == Middlewares
   #
   # Middlewares that need to manipulate the body won't work with streaming.
diff --git a/actionpack/lib/action_view/helpers/asset_tag_helper.rb b/actionpack/lib/action_view/helpers/asset_tag_helper.rb
index 02c1250c76..68b0195700 100644
--- a/actionpack/lib/action_view/helpers/asset_tag_helper.rb
+++ b/actionpack/lib/action_view/helpers/asset_tag_helper.rb
@@ -95,7 +95,7 @@ module ActionView
     # have SSL certificates for each of the asset hosts this technique allows you
     # to avoid warnings in the client about mixed media.
     #
-    #   ActionController::Base.asset_host = Proc.new { |source, request|
+    #   config.action_controller.asset_host = Proc.new { |source, request|
     #     if request.ssl?
     #       "#{request.protocol}#{request.host_with_port}"
     #     else
diff --git a/activemodel/lib/active_model/conversion.rb b/activemodel/lib/active_model/conversion.rb
index 89d87a8b6f..57b1bc2ada 100644
--- a/activemodel/lib/active_model/conversion.rb
+++ b/activemodel/lib/active_model/conversion.rb
@@ -45,18 +45,30 @@ module ActiveModel
 
     # Returns an Enumerable of all key attributes if any is set, regardless if
     # the object is persisted or not. If there no key attributes, returns +nil+.
+    #
+    #   class Person < ActiveRecord::Base
+    #   end
+    #
+    #   person = Person.create
+    #   person.to_key # => [1]
     def to_key
       key = respond_to?(:id) && id
       key ? [key] : nil
     end
 
-    # Returns a string representing the object's key suitable for use in URLs,
-    # or +nil+ if <tt>persisted?</tt> is false.
+    # Returns a +string+ representing the object's key suitable for use in URLs,
+    # or +nil+ if <tt>persisted?</tt> is +false+.
+    #
+    #   class Person < ActiveRecord::Base
+    #   end
+    #
+    #   person = Person.create
+    #   person.to_param # => "1"
     def to_param
       persisted? ? to_key.join('-') : nil
     end
 
-    # Returns a string identifying the path associated with the object.
+    # Returns a +string+ identifying the path associated with the object.
     # ActionPack uses this to find a suitable partial to represent the object.
     #
     #   class Person
diff --git a/activemodel/lib/active_model/mass_assignment_security.rb b/activemodel/lib/active_model/mass_assignment_security.rb
index 8f2c0bf00a..e57fcf1610 100644
--- a/activemodel/lib/active_model/mass_assignment_security.rb
+++ b/activemodel/lib/active_model/mass_assignment_security.rb
@@ -141,8 +141,10 @@ module ActiveModel
       #
       #     attr_accessor :name, :credit_rating
       #
-      #     attr_accessible :name
-      #     attr_accessible :name, :credit_rating, :as => :admin
+      #     # Both admin and default user can change name of a customer
+      #     attr_accessible :name, :as => [:admin, :default]
+      #     # Only admin can change credit rating of a customer
+      #     attr_accessible :credit_rating, :as => :admin
       #
       #     def assign_attributes(values, options = {})
       #       sanitize_for_mass_assignment(values, options[:as]).each do |k, v|
diff --git a/activemodel/lib/active_model/serialization.rb b/activemodel/lib/active_model/serialization.rb
index 6d8fd21814..8a63014ffb 100644
--- a/activemodel/lib/active_model/serialization.rb
+++ b/activemodel/lib/active_model/serialization.rb
@@ -25,17 +25,16 @@ module ActiveModel
   #   person.name = "Bob"
   #   person.serializable_hash   # => {"name"=>"Bob"}
   #
-  # You need to declare an attributes hash which contains the attributes
-  # you want to serialize. Attributes must be strings, not symbols.
-  # When called, serializable hash will use
-  # instance methods that match the name of the attributes hash's keys.
-  # In order to override this behavior, take a look at the private
-  # method +read_attribute_for_serialization+.
+  # You need to declare an attributes hash which contains the attributes you
+  # want to serialize. Attributes must be strings, not symbols. When called,
+  # serializable hash will use instance methods that match the name of the
+  # attributes hash's keys. In order to override this behavior, take a look at
+  # the private method +read_attribute_for_serialization+.
   #
   # Most of the time though, you will want to include the JSON or XML
   # serializations. Both of these modules automatically include the
-  # <tt>ActiveModel::Serialization</tt> module, so there is no need to explicitly
-  # include it.
+  # <tt>ActiveModel::Serialization</tt> module, so there is no need to
+  # explicitly include it.
   #
   # A minimal implementation including XML and JSON would be:
   #
@@ -64,13 +63,37 @@ module ActiveModel
   #   person.to_json             # => "{\"name\":\"Bob\"}"
   #   person.to_xml              # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<serial-person...
   #
-  # Valid options are <tt>:only</tt>, <tt>:except</tt>, <tt>:methods</tt> and <tt>:include</tt>.
-  # The following are all valid examples:
+  # Valid options are <tt>:only</tt>, <tt>:except</tt>, <tt>:methods</tt> and
+  # <tt>:include</tt>. The following are all valid examples:
   #
-  #   person.serializable_hash(:only => 'name')
-  #   person.serializable_hash(:include => :address)
-  #   person.serializable_hash(:include => { :address => { :only => 'city' }})
+  #   person.serializable_hash(only: 'name')
+  #   person.serializable_hash(include: :address)
+  #   person.serializable_hash(include: { address: { only: 'city' }})
   module Serialization
+    # Returns a serialized hash of your object.
+    #
+    #   class Person
+    #     include ActiveModel::Serialization
+    #
+    #     attr_accessor :name, :age
+    #
+    #     def attributes
+    #       {'name' => nil, 'age' => nil}
+    #     end
+    #
+    #     def capitalized_name
+    #       name.capitalize
+    #     end
+    #   end
+    #
+    #   person = Person.new
+    #   person.name = 'bob'
+    #   person.age  = 22
+    #   person.serializable_hash                # => {"name"=>"bob", "age"=>22}
+    #   person.serializable_hash(only: :name)   # => {"name"=>"bob"}
+    #   person.serializable_hash(except: :name) # => {"age"=>22}
+    #   person.serializable_hash(methods: :capitalized_name)
+    #   # => {"name"=>"bob", "age"=>22, "capitalized_name"=>"Bob"}
     def serializable_hash(options = nil)
       options ||= {}
 
@@ -115,7 +138,6 @@ module ActiveModel
       #       @data[key]
       #     end
       #   end
-      #
       alias :read_attribute_for_serialization :send
 
       # Add associations specified via the <tt>:include</tt> option.
diff --git a/activemodel/lib/active_model/validations/acceptance.rb b/activemodel/lib/active_model/validations/acceptance.rb
index 43651094cf..18e71750de 100644
--- a/activemodel/lib/active_model/validations/acceptance.rb
+++ b/activemodel/lib/active_model/validations/acceptance.rb
@@ -27,7 +27,7 @@ module ActiveModel
       #
       #   class Person < ActiveRecord::Base
       #     validates_acceptance_of :terms_of_service
-      #     validates_acceptance_of :eula, :message => "must be abided"
+      #     validates_acceptance_of :eula, message: "must be abided"
       #   end
       #
       # If the database column does not exist, the +terms_of_service+ attribute
@@ -41,23 +41,23 @@ module ActiveModel
       #   validation contexts by default (+nil+), other options are <tt>:create</tt>
       #   and <tt>:update</tt>.
       # * <tt>:allow_nil</tt> - Skip validation if attribute is +nil+ (default
-      #   is true).
+      #   is +true+).
       # * <tt>:accept</tt> - Specifies value that is considered accepted.
       #   The default value is a string "1", which makes it easy to relate to
       #   an HTML checkbox. This should be set to +true+ if you are validating
       #   a database column, since the attribute is typecast from "1" to +true+
       #   before validation.
       # * <tt>:if</tt> - Specifies a method, proc or string to call to determine
-      #   if the validation should occur (e.g. <tt>:if => :allow_validation</tt>,
-      #   or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). The
-      #   method, proc or string should return or evaluate to a true or false
-      #   value.
+      #   if the validation should occur (e.g. <tt>if: :allow_validation</tt>,
+      #   or <tt>if: Proc.new { |user| user.signup_step > 2 }</tt>). The
+      #   method, proc or string should return or evaluate to a +true+ or
+      #   +false+ value.
       # * <tt>:unless</tt> - Specifies a method, proc or string to call to
       #   determine if the validation should not occur (for example,
-      #   <tt>:unless => :skip_validation</tt>, or
-      #   <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>).
-      #   The method, proc or string should return or evaluate to a true or
-      #   false value.
+      #   <tt>unless: :skip_validation</tt>, or
+      #   <tt>unless: Proc.new { |user| user.signup_step <= 2 }</tt>).
+      #   The method, proc or string should return or evaluate to a +true+ or
+      #   +false+ value.
       # * <tt>:strict</tt> - Specifies whether validation should be strict.
       #   See <tt>ActiveModel::Validation#validates!</tt> for more information.
       def validates_acceptance_of(*attr_names)
diff --git a/activemodel/lib/active_model/validations/clusivity.rb b/activemodel/lib/active_model/validations/clusivity.rb
index b632a2bd6b..676457ec0f 100644
--- a/activemodel/lib/active_model/validations/clusivity.rb
+++ b/activemodel/lib/active_model/validations/clusivity.rb
@@ -2,7 +2,7 @@ require 'active_support/core_ext/range.rb'
 
 module ActiveModel
   module Validations
-    module Clusivity
+    module Clusivity #:nodoc:
       ERROR_MESSAGE = "An object with the method #include? or a proc or lambda is required, " <<
                       "and must be supplied as the :in option of the configuration hash"
 
diff --git a/activemodel/lib/active_model/validations/confirmation.rb b/activemodel/lib/active_model/validations/confirmation.rb
index b6cf82fb19..d41f401999 100644
--- a/activemodel/lib/active_model/validations/confirmation.rb
+++ b/activemodel/lib/active_model/validations/confirmation.rb
@@ -25,7 +25,7 @@ module ActiveModel
       #     class Person < ActiveRecord::Base
       #       validates_confirmation_of :user_name, :password
       #       validates_confirmation_of :email_address,
-      #                                 :message => "should match confirmation"
+      #                                 message: 'should match confirmation'
       #     end
       #
       #   View:
@@ -38,10 +38,10 @@ module ActiveModel
       # attribute.
       #
       # NOTE: This check is performed only if +password_confirmation+ is not
-      # +nil+. To require confirmation, make sure
-      # to add a presence check for the confirmation attribute:
+      # +nil+. To require confirmation, make sure to add a presence check for
+      # the confirmation attribute:
       #
-      #   validates_presence_of :password_confirmation, :if => :password_changed?
+      #   validates_presence_of :password_confirmation, if: :password_changed?
       #
       # Configuration options:
       # * <tt>:message</tt> - A custom error message (default is: "doesn't match
@@ -50,15 +50,16 @@ module ActiveModel
       #   validation contexts by default (+nil+), other options are <tt>:create</tt>
       #   and <tt>:update</tt>.
       # * <tt>:if</tt> - Specifies a method, proc or string to call to determine
-      #   if the validation should occur (e.g. <tt>:if => :allow_validation</tt>,
-      #   or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). The
-      #   method, proc or string should return or evaluate to a true or false
-      #   value.
+      #   if the validation should occur (e.g. <tt>if: :allow_validation</tt>,
+      #   or <tt>if: Proc.new { |user| user.signup_step > 2 }</tt>). The
+      #   method, proc or string should return or evaluate to a +true+ or
+      #   +false+ value.
       # * <tt>:unless</tt> - Specifies a method, proc or string to call to
       #   determine if the validation should not occur (e.g.
-      #   <tt>:unless => :skip_validation</tt>, or
-      #   <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>). The
-      #   method, proc or string should return or evaluate to a true or false value.
+      #   <tt>unless: :skip_validation</tt>, or
+      #   <tt>unless: Proc.new { |user| user.signup_step <= 2 }</tt>). The
+      #   method, proc or string should return or evaluate to a +true+ or
+      #   +false+ value.
       # * <tt>:strict</tt> - Specifies whether validation should be strict.
       #   See <tt>ActiveModel::Validation#validates!</tt> for more information.
       def validates_confirmation_of(*attr_names)
diff --git a/activemodel/lib/active_model/validations/exclusion.rb b/activemodel/lib/active_model/validations/exclusion.rb
index c8d7057606..a9a1af039c 100644
--- a/activemodel/lib/active_model/validations/exclusion.rb
+++ b/activemodel/lib/active_model/validations/exclusion.rb
@@ -19,35 +19,36 @@ module ActiveModel
       # particular enumerable object.
       #
       #   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 %{value} is not allowed"
-      #     validates_exclusion_of :password, :in => lambda { |p| [p.username, p.first_name] },
-      #                            :message => "should not be the same as your username or first name"
+      #     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 %{value} is not allowed"
+      #     validates_exclusion_of :password, in: ->(person) { [person.username, person.first_name] },
+      #                            message: 'should not be the same as your username or first name'
       #   end
       #
       # Configuration options:
-      # * <tt>:in</tt> - An enumerable object of items that the value shouldn't be
-      #   part of. This can be supplied as a proc or lambda which returns an
+      # * <tt>:in</tt> - An enumerable object of items that the value shouldn't
+      #   be part of. This can be supplied as a proc or lambda which returns an
       #   enumerable. If the enumerable is a range the test is performed with
       #   <tt>Range#cover?</tt>, otherwise with <tt>include?</tt>.
       # * <tt>:message</tt> - Specifies a custom error message (default is: "is
       #   reserved").
-      # * <tt>:allow_nil</tt> - If set to true, skips this validation if the attribute
-      #   is +nil+ (default is +false+).
+      # * <tt>:allow_nil</tt> - If set to true, skips this validation if the
+      #   attribute is +nil+ (default is +false+).
       # * <tt>:allow_blank</tt> - If set to true, skips this validation if the
       #   attribute is blank(default is +false+).
       # * <tt>:on</tt> - Specifies when this validation is active. Runs in all
       #   validation contexts by default (+nil+), other options are <tt>:create</tt>
       #   and <tt>:update</tt>.
       # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if
-      #   the validation should occur (e.g. <tt>:if => :allow_validation</tt>, or
-      #   <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). The method, proc
-      #   or string should return or evaluate to a true or false value.
+      #   the validation should occur (e.g. <tt>if: :allow_validation</tt>, or
+      #   <tt>if: Proc.new { |user| user.signup_step > 2 }</tt>). The method,
+      #   proc or string should return or evaluate to a +true+ or +false+ value.
       # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine
-      #   if the validation should not occur (e.g. <tt>:unless => :skip_validation</tt>,
-      #   or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>). The
-      #   method, proc or string should return or evaluate to a true or false value.
+      #   if the validation should not occur (e.g. <tt>unless: :skip_validation</tt>,
+      #   or <tt>unless: Proc.new { |user| user.signup_step <= 2 }</tt>). The
+      #   method, proc or string should return or evaluate to a +true+ or
+      #   +false+ value.
       # * <tt>:strict</tt> - Specifies whether validation should be strict.
       #   See <tt>ActiveModel::Validation#validates!</tt> for more information.
       def validates_exclusion_of(*attr_names)
diff --git a/activemodel/lib/active_model/validations/format.rb b/activemodel/lib/active_model/validations/format.rb
index d48987c482..a2126f8372 100644
--- a/activemodel/lib/active_model/validations/format.rb
+++ b/activemodel/lib/active_model/validations/format.rb
@@ -57,14 +57,14 @@ module ActiveModel
       # attribute matches the regular expression:
       #
       #   class Person < ActiveRecord::Base
-      #     validates_format_of :email, :with => /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\z/i, :on => :create
+      #     validates_format_of :email, with: /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\z/i, on: :create
       #   end
       #
       # Alternatively, you can require that the specified attribute does _not_
       # match the regular expression:
       #
       #   class Person < ActiveRecord::Base
-      #     validates_format_of :email, :without => /NOSPAM/
+      #     validates_format_of :email, without: /NOSPAM/
       #   end
       #
       # You can also provide a proc or lambda which will determine the regular
@@ -73,15 +73,16 @@ module ActiveModel
       #   class Person < ActiveRecord::Base
       #     # Admin can have number as a first letter in their screen name
       #     validates_format_of :screen_name,
-      #                         :with => lambda{ |person| person.admin? ? /\A[a-z0-9][a-z0-9_\-]*\z/i : /\A[a-z][a-z0-9_\-]*\z/i }
+      #                         with: ->(person) { person.admin? ? /\A[a-z0-9][a-z0-9_\-]*\z/i : /\A[a-z][a-z0-9_\-]*\z/i }
       #   end
       #
       # Note: use <tt>\A</tt> and <tt>\Z</tt> to match the start and end of the
       # string, <tt>^</tt> and <tt>$</tt> match the start/end of a line.
       #
-      # Due to frequent misuse of <tt>^</tt> and <tt>$</tt>, you need to pass the
-      # :multiline => true option in case you use any of these two anchors in the provided
-      # regular expression. In most cases, you should be using <tt>\A</tt> and <tt>\z</tt>.
+      # Due to frequent misuse of <tt>^</tt> and <tt>$</tt>, you need to pass
+      # the <tt>multiline: true</tt> option in case you use any of these two
+      # anchors in the provided regular expression. In most cases, you should be
+      # using <tt>\A</tt> and <tt>\z</tt>.
       #
       # You must pass either <tt>:with</tt> or <tt>:without</tt> as an option.
       # In addition, both must be a regular expression or a proc or lambda, or
@@ -89,27 +90,29 @@ module ActiveModel
       #
       # Configuration options:
       # * <tt>:message</tt> - A custom error message (default is: "is invalid").
-      # * <tt>:allow_nil</tt> - If set to true, skips this validation if the attribute
-      #   is +nil+ (default is +false+).
+      # * <tt>:allow_nil</tt> - If set to true, skips this validation if the
+      #   attribute is +nil+ (default is +false+).
       # * <tt>:allow_blank</tt> - If set to true, skips this validation if the
       #   attribute is blank (default is +false+).
       # * <tt>:with</tt> - Regular expression that if the attribute matches will
-      #   result in a successful validation. This can be provided as a proc or lambda
-      #   returning regular expression which will be called at runtime.
-      # * <tt>:without</tt> - Regular expression that if the attribute does not match
-      #   will result in a successful validation. This can be provided as a proc or
+      #   result in a successful validation. This can be provided as a proc or
       #   lambda returning regular expression which will be called at runtime.
+      # * <tt>:without</tt> - Regular expression that if the attribute does not
+      #   match will result in a successful validation. This can be provided as
+      #   a proc or lambda returning regular expression which will be called at
+      #   runtime.
       # * <tt>:on</tt> - Specifies when this validation is active. Runs in all
       #   validation contexts by default (+nil+), other options are <tt>:create</tt>
       #   and <tt>:update</tt>.
       # * <tt>:if</tt> - Specifies a method, proc or string to call to determine
-      #   if the validation should occur (e.g. <tt>:if => :allow_validation</tt>, or
-      #   <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). The method, proc
-      #   or string should return or evaluate to a true or false value.
+      #   if the validation should occur (e.g. <tt>if: :allow_validation</tt>,
+      #   or <tt>if: Proc.new { |user| user.signup_step > 2 }</tt>). The method,
+      #   proc or string should return or evaluate to a +true+ or +false+ value.
       # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine
-      #   if the validation should not occur (e.g. <tt>:unless => :skip_validation</tt>,
-      #   or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>). The
-      #   method, proc or string should return or evaluate to a true or false value.
+      #   if the validation should not occur (e.g. <tt>unless: :skip_validation</tt>,
+      #   or <tt>unless: Proc.new { |user| user.signup_step <= 2 }</tt>). The
+      #   method, proc or string should return or evaluate to a +true+ or
+      #   +false+ value.
       # * <tt>:strict</tt> - Specifies whether validation should be strict.
       #   See <tt>ActiveModel::Validation#validates!</tt> for more information.
       # * <tt>:multiline</tt> - Set to true if your regular expression contains
diff --git a/activemodel/lib/active_model/validations/inclusion.rb b/activemodel/lib/active_model/validations/inclusion.rb
index 154db5aedc..e7ad07f040 100644
--- a/activemodel/lib/active_model/validations/inclusion.rb
+++ b/activemodel/lib/active_model/validations/inclusion.rb
@@ -19,34 +19,35 @@ module ActiveModel
       # particular enumerable object.
       #
       #   class Person < ActiveRecord::Base
-      #     validates_inclusion_of :gender, :in => %w( m f )
-      #     validates_inclusion_of :age, :in => 0..99
-      #     validates_inclusion_of :format, :in => %w( jpg gif png ), :message => "extension %{value} is not included in the list"
-      #     validates_inclusion_of :states, :in => lambda{ |person| STATES[person.country] }
+      #     validates_inclusion_of :gender, in: %w( m f )
+      #     validates_inclusion_of :age, in: 0..99
+      #     validates_inclusion_of :format, in: %w( jpg gif png ), message: "extension %{value} is not included in the list"
+      #     validates_inclusion_of :states, in: ->(person) { STATES[person.country] }
       #   end
       #
       # Configuration options:
       # * <tt>:in</tt> - An enumerable object of available items. This can be
-      #   supplied as a proc or lambda which returns an enumerable. If the enumerable
-      #   is a range the test is performed with <tt>Range#cover?</tt>, otherwise with
-      #   <tt>include?</tt>.
-      # * <tt>:message</tt> - Specifies a custom error message (default is: "is not
-      #   included in the list").
-      # * <tt>:allow_nil</tt> - If set to true, skips this validation if the attribute
-      #   is +nil+ (default is +false+).
-      # * <tt>:allow_blank</tt> - If set to true, skips this validation if the
+      #   supplied as a proc or lambda which returns an enumerable. If the
+      #   enumerable is a range the test is performed with <tt>Range#cover?</tt>,
+      #   otherwise with <tt>include?</tt>.
+      # * <tt>:message</tt> - Specifies a custom error message (default is: "is
+      #   not included in the list").
+      # * <tt>:allow_nil</tt> - If set to +true+, skips this validation if the
+      #   attribute is +nil+ (default is +false+).
+      # * <tt>:allow_blank</tt> - If set to +true+, skips this validation if the
       #   attribute is blank (default is +false+).
       # * <tt>:on</tt> - Specifies when this validation is active. Runs in all
       #   validation contexts by default (+nil+), other options are <tt>:create</tt>
       #   and <tt>:update</tt>.
       # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if
-      #   the validation should occur (e.g. <tt>:if => :allow_validation</tt>, or
-      #   <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). The method, proc
-      #   or string should return or evaluate to a true or false value.
+      #   the validation should occur (e.g. <tt>if: :allow_validation</tt>, or
+      #   <tt>if: Proc.new { |user| user.signup_step > 2 }</tt>). The method, proc
+      #   or string should return or evaluate to a +true+ or +false+ value.
       # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine
-      #   if the validation should not occur (e.g. <tt>:unless => :skip_validation</tt>,
-      #   or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>). The
-      #   method, proc or string should return or evaluate to a true or false value.
+      #   if the validation should not occur (e.g. <tt>unless: :skip_validation</tt>,
+      #   or <tt>unless: Proc.new { |user| user.signup_step <= 2 }</tt>). The
+      #   method, proc or string should return or evaluate to a +true+ or
+      #   +false+ value.
       # * <tt>:strict</tt> - Specifies whether validation should be strict.
       #   See <tt>ActiveModel::Validation#validates!</tt> for more information.
       def validates_inclusion_of(*attr_names)
diff --git a/activemodel/lib/active_model/validations/length.rb b/activemodel/lib/active_model/validations/length.rb
index 40ebe0cd2e..3b0be96ac6 100644
--- a/activemodel/lib/active_model/validations/length.rb
+++ b/activemodel/lib/active_model/validations/length.rb
@@ -62,36 +62,37 @@ module ActiveModel
 
     module HelperMethods
 
-      # Validates that the specified attribute matches the length restrictions supplied. Only one option can be used at a time:
+      # Validates that the specified attribute matches the length restrictions
+      # supplied. Only one option can be used at a time:
       #
       #   class Person < ActiveRecord::Base
-      #     validates_length_of :first_name, :maximum => 30
-      #     validates_length_of :last_name, :maximum => 30, :message => "less than 30 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 :zip_code, :minimum => 5, :too_short => "please enter at least 5 characters"
-      #     validates_length_of :smurf_leader, :is => 4, :message => "papa is spelled with 4 characters... don't play me."
-      #     validates_length_of :essay, :minimum => 100, :too_short => "Your essay must be at least 100 words.",
-      #                         :tokenizer => lambda { |str| str.scan(/\w+/) }
+      #     validates_length_of :first_name, maximum: 30
+      #     validates_length_of :last_name, maximum: 30, message: "less than 30 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 :zip_code, minimum: 5, too_short: 'please enter at least 5 characters'
+      #     validates_length_of :smurf_leader, is: 4, message: "papa is spelled with 4 characters... don't play me."
+      #     validates_length_of :essay, minimum: 100, too_short: 'Your essay must be at least 100 words.',
+      #                         tokenizer: ->(str) { str.scan(/\w+/) }
       #   end
       #
       # Configuration options:
       # * <tt>:minimum</tt> - The minimum size of the attribute.
       # * <tt>:maximum</tt> - The maximum size of the attribute.
       # * <tt>:is</tt> - The exact size of the attribute.
-      # * <tt>:within</tt> - A range specifying the minimum and maximum size of the
-      #   attribute.
-      # * <tt>:in</tt> - A synonym(or alias) for <tt>:within</tt>.
+      # * <tt>:within</tt> - A range specifying the minimum and maximum size of
+      #   the attribute.
+      # * <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 %{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>: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.
@@ -99,16 +100,17 @@ module ActiveModel
       #   validation contexts by default (+nil+), other options are <tt>:create</tt>
       #   and <tt>:update</tt>.
       # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if
-      #   the validation should occur (e.g. <tt>:if => :allow_validation</tt>, or
-      #   <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). The method, proc
-      #   or string should return or evaluate to a true or false value.
+      #   the validation should occur (e.g. <tt>if: :allow_validation</tt>, or
+      #   <tt>if: Proc.new { |user| user.signup_step > 2 }</tt>). The method,
+      #   proc or string should return or evaluate to a +true+ or +false+ value.
       # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine
-      #   if the validation should not occur (e.g. <tt>:unless => :skip_validation</tt>,
-      #   or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>). The method,
-      #   proc or string should return or evaluate to a true or false value.
+      #   if the validation should not occur (e.g. <tt>unless: :skip_validation</tt>,
+      #   or <tt>unless: Proc.new { |user| user.signup_step <= 2 }</tt>). The
+      #   method, proc or string should return or evaluate to a +true+ or
+      #   +false+ value.
       # * <tt>:tokenizer</tt> - Specifies how to split up the attribute string.
-      #   (e.g. <tt>:tokenizer => lambda {|str| str.scan(/\w+/)}</tt> to count words
-      #   as in above example). Defaults to <tt>lambda{ |value| value.split(//) }</tt>
+      #   (e.g. <tt>tokenizer: ->(str) { str.scan(/\w+/) }</tt> to count words
+      #   as in above example). Defaults to <tt>->(value) { value.split(//) }</tt>
       #   which counts individual characters.
       # * <tt>:strict</tt> - Specifies whether validation should be strict.
       #   See <tt>ActiveModel::Validation#validates!</tt> for more information.
diff --git a/activemodel/lib/active_model/validations/numericality.rb b/activemodel/lib/active_model/validations/numericality.rb
index 1069ed3906..6b3dd6caec 100644
--- a/activemodel/lib/active_model/validations/numericality.rb
+++ b/activemodel/lib/active_model/validations/numericality.rb
@@ -79,13 +79,13 @@ module ActiveModel
     end
 
     module HelperMethods
-      # Validates whether the value of the specified attribute is numeric by trying
-      # to convert it to a float with Kernel.Float (if <tt>only_integer</tt> is false)
-      # or applying it to the regular expression <tt>/\A[\+\-]?\d+\Z/</tt> (if
-      # <tt>only_integer</tt> is set to true).
+      # Validates whether the value of the specified attribute is numeric by
+      # trying to convert it to a float with Kernel.Float (if <tt>only_integer</tt>
+      # is +false+) or applying it to the regular expression <tt>/\A[\+\-]?\d+\Z/</tt>
+      # (if <tt>only_integer</tt> is set to +true+).
       #
       #   class Person < ActiveRecord::Base
-      #     validates_numericality_of :value, :on => :create
+      #     validates_numericality_of :value, on: :create
       #   end
       #
       # Configuration options:
@@ -93,32 +93,34 @@ module ActiveModel
       # * <tt>:on</tt> - Specifies when this validation is active. Runs in all
       #   validation contexts by default (+nil+), other options are <tt>:create</tt>
       #   and <tt>:update</tt>.
-      # * <tt>:only_integer</tt> - Specifies whether the value has to be an integer,
-      #   e.g. an integral value (default is +false+).
+      # * <tt>:only_integer</tt> - Specifies whether the value has to be an
+      #   integer, e.g. an integral value (default is +false+).
       # * <tt>:allow_nil</tt> - Skip validation if attribute is +nil+ (default is
       #   +false+). Notice that for fixnum and float columns empty strings are
       #   converted to +nil+.
       # * <tt>:greater_than</tt> - Specifies the value must be greater than the
       #   supplied value.
-      # * <tt>:greater_than_or_equal_to</tt> - Specifies the value must be greater
-      #   than or equal the supplied value.
-      # * <tt>:equal_to</tt> - Specifies the value must be equal to the supplied value.
-      # * <tt>:less_than</tt> - Specifies the value must be less than the supplied
-      #   value.
-      # * <tt>:less_than_or_equal_to</tt> - Specifies the value must be less than or
-      #   equal the supplied value.
-      # * <tt>:other_than</tt> - Specifies the value must be other than the supplied
+      # * <tt>:greater_than_or_equal_to</tt> - Specifies the value must be
+      #   greater than or equal the supplied value.
+      # * <tt>:equal_to</tt> - Specifies the value must be equal to the supplied
       #   value.
+      # * <tt>:less_than</tt> - Specifies the value must be less than the
+      #   supplied value.
+      # * <tt>:less_than_or_equal_to</tt> - Specifies the value must be less
+      #   than or equal the supplied value.
+      # * <tt>:other_than</tt> - Specifies the value must be other than the
+      #   supplied value.
       # * <tt>:odd</tt> - Specifies the value must be an odd number.
       # * <tt>:even</tt> - Specifies the value must be an even number.
-      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if
-      #   the validation should occur (e.g. <tt>:if => :allow_validation</tt>, or
-      #   <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). The method, proc
-      #   or string should return or evaluate to a true or false value.
+      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine
+      #   if the validation should occur (e.g. <tt>if: :allow_validation</tt>,
+      #   or <tt>if: Proc.new { |user| user.signup_step > 2 }</tt>). The method,
+      #   proc or string should return or evaluate to a +true+ or +false+ value.
       # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine
-      #   if the validation should not occur (e.g. <tt>:unless => :skip_validation</tt>,
-      #   or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>). The
-      #   method, proc or string should return or evaluate to a true or false value.
+      #   if the validation should not occur (e.g. <tt>unless: :skip_validation</tt>,
+      #   or <tt>unless: Proc.new { |user| user.signup_step <= 2 }</tt>). The
+      #   method, proc or string should return or evaluate to a +true+ or
+      #   +false+ value.
       # * <tt>:strict</tt> - Specifies whether validation should be strict.
       #   See <tt>ActiveModel::Validation#validates!</tt> for more information.
       #
@@ -134,8 +136,8 @@ module ActiveModel
       # For example:
       #
       #   class Person < ActiveRecord::Base
-      #     validates_numericality_of :width, :less_than => Proc.new { |person| person.height }
-      #     validates_numericality_of :width, :greater_than => :minimum_weight
+      #     validates_numericality_of :width, less_than: Proc.new { |person| person.height }
+      #     validates_numericality_of :width, greater_than: :minimum_weight
       #   end
       def validates_numericality_of(*attr_names)
         validates_with NumericalityValidator, _merge_attributes(attr_names)
diff --git a/activemodel/lib/active_model/validations/presence.rb b/activemodel/lib/active_model/validations/presence.rb
index a7dcdbba3d..cb7e9104db 100644
--- a/activemodel/lib/active_model/validations/presence.rb
+++ b/activemodel/lib/active_model/validations/presence.rb
@@ -20,9 +20,9 @@ module ActiveModel
       #
       # The first_name attribute must be in the object and it cannot be blank.
       #
-      # If you want to validate the presence of a boolean field (where the real values
-      # are true and false), you will want to use
-      # <tt>validates_inclusion_of :field_name, :in => [true, false]</tt>.
+      # If you want to validate the presence of a boolean field (where the real
+      # values are +true+ and +false+), you will want to use
+      # <tt>validates_inclusion_of :field_name, in: [true, false]</tt>.
       #
       # This is due to the way Object#blank? handles boolean values:
       # <tt>false.blank? # => true</tt>.
@@ -32,14 +32,15 @@ module ActiveModel
       # * <tt>:on</tt> - Specifies when this validation is active. Runs in all
       #   validation contexts by default (+nil+), other options are <tt>:create</tt>
       #   and <tt>:update</tt>.
-      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if
-      #   the validation should occur (e.g. <tt>:if => :allow_validation</tt>, or
-      #   <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). The method, proc
-      #   or string should return or evaluate to a true or false value.
+      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine
+      #   if the validation should occur (e.g. <tt>if: :allow_validation</tt>,
+      #   or <tt>if: Proc.new { |user| user.signup_step > 2 }</tt>). The method,
+      #   proc or string should return or evaluate to a +true+ or +false+ value.
       # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine
-      #   if the validation should not occur (e.g. <tt>:unless => :skip_validation</tt>,
-      #   or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>). The method,
-      #   proc or string should return or evaluate to a true or false value.
+      #   if the validation should not occur (e.g. <tt>unless: :skip_validation</tt>,
+      #   or <tt>unless: Proc.new { |user| user.signup_step <= 2 }</tt>). The
+      #   method, proc or string should return or evaluate to a +true+ or
+      #   +false+ value.
       # * <tt>:strict</tt> - Specifies whether validation should be strict.
       #   See <tt>ActiveModel::Validation#validates!</tt> for more information.
       def validates_presence_of(*attr_names)
diff --git a/activemodel/lib/active_model/validator.rb b/activemodel/lib/active_model/validator.rb
index 2953126c3c..d5d0798704 100644
--- a/activemodel/lib/active_model/validator.rb
+++ b/activemodel/lib/active_model/validator.rb
@@ -129,7 +129,7 @@ module ActiveModel #:nodoc:
   # record, attribute and value.
   #
   # All Active Model validations are built on top of this validator.
-  class EachValidator < Validator
+  class EachValidator < Validator #:nodoc:
     attr_reader :attributes
 
     # Returns a new validator instance. All options will be available via the
@@ -168,7 +168,7 @@ module ActiveModel #:nodoc:
 
   # +BlockValidator+ is a special +EachValidator+ which receives a block on initialization
   # and call this block for each attribute being validated. +validates_each+ uses this validator.
-  class BlockValidator < EachValidator
+  class BlockValidator < EachValidator #:nodoc:
     def initialize(options, &block)
       @block = block
       super
diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
index 65c7ef0153..3c3f01223c 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
@@ -57,7 +57,6 @@ module ActiveRecord
 
       # Checks to see if a column exists in a given table.
       #
-      # === Examples
       #  # Check a column exists
       #  column_exists?(:suppliers, :name)
       #
@@ -65,7 +64,10 @@ module ActiveRecord
       #  column_exists?(:suppliers, :name, :string)
       #
       #  # Check a column exists with a specific definition
-      #  column_exists?(:suppliers, :name, :string, :limit => 100)
+      #  column_exists?(:suppliers, :name, :string, limit: 100)
+      #  column_exists?(:suppliers, :name, :string, default: 'default')
+      #  column_exists?(:suppliers, :name, :string, null: false)
+      #  column_exists?(:suppliers, :tax, :decimal, precision: 8, scale: 2)
       def column_exists?(table_name, column_name, type = nil, options = {})
         columns(table_name).any?{ |c| c.name == column_name.to_s &&
                                       (!type                     || c.type == type) &&
diff --git a/activerecord/lib/active_record/relation/query_methods.rb b/activerecord/lib/active_record/relation/query_methods.rb
index 6f49548aab..e401ed37b0 100644
--- a/activerecord/lib/active_record/relation/query_methods.rb
+++ b/activerecord/lib/active_record/relation/query_methods.rb
@@ -41,6 +41,17 @@ module ActiveRecord
 
     alias extensions extending_values
 
+    # Specify relationships to be included in the result set. For
+    # example:
+    #
+    #   users = User.includes(:address)
+    #   users.each do |user|
+    #     user.address.city
+    #   end
+    #
+    # allows you to access the +address+ attribute of the +User+ model without
+    # firing an additional query. This will often result in a
+    # performance improvement over a simple +join+
     def includes(*args)
       args.empty? ? self : spawn.includes!(*args)
     end
@@ -131,6 +142,18 @@ module ActiveRecord
       self
     end
 
+    # Allows to specify a group attribute:
+    #
+    #   User.group(:name)
+    #   => SELECT "users".* FROM "users" GROUP BY name
+    #
+    # Returns an array with distinct records based on the `group` attribute:
+    #
+    #   User.select([:id, :name])
+    #   => [#<User id: 1, name: "Oscar">, #<User id: 2, name: "Oscar">, #<User id: 3, name: "Foo">
+    #
+    #   User.group(:name)
+    #   => [#<User id: 3, name: "Foo", ...>, #<User id: 2, name: "Oscar", ...>]
     def group(*args)
       args.blank? ? self : spawn.group!(*args)
     end
@@ -142,6 +165,16 @@ module ActiveRecord
       self
     end
 
+    # Allows to specify an order attribute:
+    #
+    #   User.order('name')
+    #   => SELECT "users".* FROM "users" ORDER BY name
+    #
+    #   User.order('name DESC')
+    #   => SELECT "users".* FROM "users" ORDER BY name DESC
+    #
+    #   User.order('name DESC, email')
+    #   => SELECT "users".* FROM "users" ORDER BY name DESC, email
     def order(*args)
       args.blank? ? self : spawn.order!(*args)
     end
diff --git a/activerecord/lib/active_record/scoping/default.rb b/activerecord/lib/active_record/scoping/default.rb
index af51c803a7..b35fec7920 100644
--- a/activerecord/lib/active_record/scoping/default.rb
+++ b/activerecord/lib/active_record/scoping/default.rb
@@ -31,14 +31,14 @@ module ActiveRecord
         #     Post.limit(10) # Fires "SELECT * FROM posts LIMIT 10"
         #   }
         #
-        # It is recommended that you use the block form of unscoped because chaining
-        # unscoped with <tt>scope</tt> does not work.  Assuming that
+        # It is recommended that you use the block form of unscoped because
+        # chaining unscoped with <tt>scope</tt> does not work. Assuming that
         # <tt>published</tt> is a <tt>scope</tt>, the following two statements
-        # are equal: the default_scope is applied on both.
+        # are equal: the <tt>default_scope</tt> is applied on both.
         #
         #   Post.unscoped.published
         #   Post.published
-        def unscoped #:nodoc:
+        def unscoped
           block_given? ? relation.scoping { yield } : relation
         end
 
diff --git a/guides/source/active_record_querying.textile b/guides/source/active_record_querying.textile
index 101988c59e..9863d16fda 100644
--- a/guides/source/active_record_querying.textile
+++ b/guides/source/active_record_querying.textile
@@ -12,8 +12,6 @@ This guide covers different ways to retrieve data from the database using Active
 
 endprologue.
 
-WARNING. This Guide is based on Rails 3.0. Some of the code shown here will not work in other versions of Rails.
-
 If you're used to using raw SQL to find database records, then you will generally find that there are better ways to carry out the same operations in Rails. Active Record insulates you from the need to use SQL in most cases.
 
 Code examples throughout this guide will refer to one or more of the following models:
@@ -53,20 +51,26 @@ h3. Retrieving Objects from the Database
 To retrieve objects from the database, Active Record provides several finder methods. Each finder method allows you to pass arguments into it to perform certain queries on your database without writing raw SQL.
 
 The methods are:
-* +where+
-* +select+
+* +bind+
+* +create_with+
+* +extending+
+* +from+
 * +group+
-* +order+
-* +reorder+
-* +reverse_order+
-* +limit+
-* +offset+
-* +joins+
+* +having+
 * +includes+
+* +joins+
+* +limit+
 * +lock+
+* +offset+
+* +order+
+* +none+
 * +readonly+
-* +from+
-* +having+
+* +references+
+* +reorder+
+* +reverse_order+
+* +select+
+* +uniq+
+* +where+
 
 All of the above methods return an instance of <tt>ActiveRecord::Relation</tt>.
 
diff --git a/railties/lib/rails/engine.rb b/railties/lib/rails/engine.rb
index 383c159d3d..f469c334a7 100644
--- a/railties/lib/rails/engine.rb
+++ b/railties/lib/rails/engine.rb
@@ -176,8 +176,7 @@ module Rails
   #
   # * routes: when you mount an Engine with <tt>mount(MyEngine::Engine => '/my_engine')</tt>,
   #   it's used as default :as option
-  # * some of the rake tasks are based on engine name, e.g. <tt>my_engine:install:migrations</tt>,
-  #   <tt>my_engine:install:assets</tt>
+  # * rake task for installing migrations <tt>my_engine:install:migrations</tt>
   #
   # Engine name is set by default based on class name. For <tt>MyEngine::Engine</tt> it will be
   # <tt>my_engine_engine</tt>. You can change it manually using the <tt>engine_name</tt> method: