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

Conflicts: activemodel/lib/active_model/secure_password.rb activerecord/lib/active_record/associations/collection_proxy.rb
author: Vijay Dev <vijaydev.cse@gmail.com> 2012-08-04 15:18:35 +0530
committer: Vijay Dev <vijaydev.cse@gmail.com> 2012-08-04 15:18:35 +0530
commit: 3d3fa165e40c8cdaaebdab9dd2985d0ca3a36236 (patch)
tree: 21ae9b984d34c9487628097f3933f8fa14a3558f /activemodel
parent: c963f883a41913624363bfd8203b5640318198c2 (diff)
parent: b51201242aaf77c6db5a9b2f72e433c521df79c5 (diff)
download: rails-3d3fa165e40c8cdaaebdab9dd2985d0ca3a36236.tar.gz
rails-3d3fa165e40c8cdaaebdab9dd2985d0ca3a36236.tar.bz2
rails-3d3fa165e40c8cdaaebdab9dd2985d0ca3a36236.zip
15 files changed, 765 insertions, 278 deletions
diff --git a/activemodel/lib/active_model/attribute_methods.rb b/activemodel/lib/active_model/attribute_methods.rb
index 21b1209875..ef04f1fa49 100644
--- a/activemodel/lib/active_model/attribute_methods.rb
+++ b/activemodel/lib/active_model/attribute_methods.rb
@@ -1,6 +1,14 @@
 
 module ActiveModel
   # Raised when an attribute is not defined.
+  #
+  #   class User < ActiveRecord::Base
+  #     has_many :pets
+  #   end
+  #
+  #   user = User.first
+  #   user.pets.select(:id).first.user_id
+  #   # => ActiveModel::MissingAttributeError: missing attribute: user_id
   class MissingAttributeError < NoMethodError
   end
   # == Active Model Attribute Methods
diff --git a/activemodel/lib/active_model/errors.rb b/activemodel/lib/active_model/errors.rb
index d68086584e..1026b0f4d3 100644
--- a/activemodel/lib/active_model/errors.rb
+++ b/activemodel/lib/active_model/errors.rb
@@ -436,6 +436,19 @@ module ActiveModel
 
   # Raised when a validation cannot be corrected by end users and are considered
   # exceptional.
+  #
+  #   class Person
+  #     include ActiveModel::Validations
+  #
+  #     attr_accessor :name
+  #
+  #     validates_presence_of :name, strict: true
+  #   end
+  #
+  #   person = Person.new
+  #   person.name = nil
+  #   person.valid?
+  #   # => ActiveModel::StrictValidationFailed: Name can't be blank
   class StrictValidationFailed < StandardError
   end
 end
diff --git a/activemodel/lib/active_model/mass_assignment_security.rb b/activemodel/lib/active_model/mass_assignment_security.rb
index 87c0bcf59b..f9841abcb0 100644
--- a/activemodel/lib/active_model/mass_assignment_security.rb
+++ b/activemodel/lib/active_model/mass_assignment_security.rb
@@ -3,7 +3,48 @@ require 'active_model/mass_assignment_security/permission_set'
 require 'active_model/mass_assignment_security/sanitizer'
 
 module ActiveModel
-  # = Active Model Mass-Assignment Security
+  # == Active Model Mass-Assignment Security
+  #
+  # Mass assignment security provides an interface for protecting attributes
+  # from end-user assignment. For more complex permissions, mass assignment
+  # security may be handled outside the model by extending a non-ActiveRecord
+  # class, such as a controller, with this behavior.
+  #
+  # For example, a logged in user may need to assign additional attributes
+  # depending on their role:
+  #
+  #   class AccountsController < ApplicationController
+  #     include ActiveModel::MassAssignmentSecurity
+  #
+  #     attr_accessible :first_name, :last_name
+  #     attr_accessible :first_name, :last_name, :plan_id, as: :admin
+  #
+  #     def update
+  #       ...
+  #       @account.update_attributes(account_params)
+  #       ...
+  #     end
+  #
+  #     protected
+  #
+  #     def account_params
+  #       role = admin ? :admin : :default
+  #       sanitize_for_mass_assignment(params[:account], role)
+  #     end
+  #
+  #   end
+  #
+  # === Configuration options
+  #
+  # * <tt>mass_assignment_sanitizer</tt> - Defines sanitize method. Possible
+  #   values are:
+  #   * <tt>:logger</tt> (default) - writes filtered attributes to logger
+  #   * <tt>:strict</tt> - raise <tt>ActiveModel::MassAssignmentSecurity::Error</tt>
+  #     on any protected attribute update.
+  #
+  # You can specify your own sanitizer object eg. <tt>MySanitizer.new</tt>.
+  # See <tt>ActiveModel::MassAssignmentSecurity::LoggerSanitizer</tt> for
+  # example implementation.
   module MassAssignmentSecurity
     extend ActiveSupport::Concern
 
@@ -16,55 +57,17 @@ module ActiveModel
       self.mass_assignment_sanitizer = :logger
     end
 
-    # Mass assignment security provides an interface for protecting attributes
-    # from end-user assignment. For more complex permissions, mass assignment security
-    # may be handled outside the model by extending a non-ActiveRecord class,
-    # such as a controller, with this behavior.
-    #
-    # For example, a logged in user may need to assign additional attributes depending
-    # on their role:
-    #
-    #   class AccountsController < ApplicationController
-    #     include ActiveModel::MassAssignmentSecurity
-    #
-    #     attr_accessible :first_name, :last_name
-    #     attr_accessible :first_name, :last_name, :plan_id, :as => :admin
-    #
-    #     def update
-    #       ...
-    #       @account.update_attributes(account_params)
-    #       ...
-    #     end
-    #
-    #     protected
-    #
-    #     def account_params
-    #       role = admin ? :admin : :default
-    #       sanitize_for_mass_assignment(params[:account], role)
-    #     end
-    #
-    #   end
-    #
-    # = Configuration options
-    #
-    # * <tt>mass_assignment_sanitizer</tt> - Defines sanitize method. Possible values are:
-    #   * <tt>:logger</tt> (default) - writes filtered attributes to logger
-    #   * <tt>:strict</tt> - raise <tt>ActiveModel::MassAssignmentSecurity::Error</tt> on any protected attribute update
-    #
-    # You can specify your own sanitizer object eg. MySanitizer.new.
-    # See <tt>ActiveModel::MassAssignmentSecurity::LoggerSanitizer</tt> for example implementation.
-    #
-    #
     module ClassMethods
       # Attributes named in this macro are protected from mass-assignment
       # whenever attributes are sanitized before assignment. A role for the
-      # attributes is optional, if no role is provided then :default is used.
-      # A role can be defined by using the :as option with a symbol or an array of symbols as the value.
+      # attributes is optional, if no role is provided then <tt>:default</tt>
+      # is used. A role can be defined by using the <tt>:as</tt> option with a
+      # symbol or an array of symbols as the value.
       #
       # Mass-assignment to these attributes will simply be ignored, to assign
       # to them you can use direct writer methods. This is meant to protect
       # sensitive attributes from being overwritten by malicious users
-      # tampering with URLs or forms. Example:
+      # tampering with URLs or forms.
       #
       #   class Customer
       #     include ActiveModel::MassAssignmentSecurity
@@ -73,7 +76,7 @@ module ActiveModel
       #
       #     attr_protected :logins_count
       #     # Suppose that admin can not change email for customer
-      #     attr_protected :logins_count, :email, :as => :admin
+      #     attr_protected :logins_count, :email, as: :admin
       #
       #     def assign_attributes(values, options = {})
       #       sanitize_for_mass_assignment(values, options[:as]).each do |k, v|
@@ -82,23 +85,23 @@ module ActiveModel
       #     end
       #   end
       #
-      # When using the :default role:
+      # When using the <tt>:default</tt> role:
       #
       #   customer = Customer.new
-      #   customer.assign_attributes({ "name" => "David", "email" => "a@b.com", :logins_count => 5 }, :as => :default)
-      #   customer.name          # => "David"
-      #   customer.email # => "a@b.com"
-      #   customer.logins_count    # => nil
+      #   customer.assign_attributes({ name: 'David', email: 'a@b.com', logins_count: 5 }, as: :default)
+      #   customer.name         # => "David"
+      #   customer.email        # => "a@b.com"
+      #   customer.logins_count # => nil
       #
-      # And using the :admin role:
+      # And using the <tt>:admin</tt> role:
       #
       #   customer = Customer.new
-      #   customer.assign_attributes({ "name" => "David", "email" => "a@b.com", :logins_count => 5}, :as => :admin)
-      #   customer.name          # => "David"
-      #   customer.email # => nil
-      #   customer.logins_count    # => nil
+      #   customer.assign_attributes({ name: 'David', email: 'a@b.com', logins_count: 5}, as: :admin)
+      #   customer.name         # => "David"
+      #   customer.email        # => nil
+      #   customer.logins_count # => nil
       #
-      #   customer.email = "c@d.com"
+      #   customer.email = 'c@d.com'
       #   customer.email # => "c@d.com"
       #
       # To start from an all-closed default and enable attributes as needed,
@@ -124,8 +127,9 @@ module ActiveModel
       # mass-assignment.
       #
       # Like +attr_protected+, a role for the attributes is optional,
-      # if no role is provided then :default is used. A role can be defined by
-      # using the :as option with a symbol or an array of symbols as the value.
+      # if no role is provided then <tt>:default</tt> is used. A role can be
+      # defined by using the <tt>:as</tt> option with a symbol or an array of
+      # symbols as the value.
       #
       # This is the opposite of the +attr_protected+ macro: Mass-assignment
       # will only set attributes in this list, to assign to the rest of
@@ -141,9 +145,9 @@ module ActiveModel
       #     attr_accessor :name, :credit_rating
       #
       #     # Both admin and default user can change name of a customer
-      #     attr_accessible :name, :as => [:admin, :default]
+      #     attr_accessible :name, as: [:admin, :default]
       #     # Only admin can change credit rating of a customer
-      #     attr_accessible :credit_rating, :as => :admin
+      #     attr_accessible :credit_rating, as: :admin
       #
       #     def assign_attributes(values, options = {})
       #       sanitize_for_mass_assignment(values, options[:as]).each do |k, v|
@@ -152,20 +156,20 @@ module ActiveModel
       #     end
       #   end
       #
-      # When using the :default role:
+      # When using the <tt>:default</tt> role:
       #
       #   customer = Customer.new
-      #   customer.assign_attributes({ "name" => "David", "credit_rating" => "Excellent", :last_login => 1.day.ago }, :as => :default)
+      #   customer.assign_attributes({ name: 'David', credit_rating: 'Excellent', last_login: 1.day.ago }, as: :default)
       #   customer.name          # => "David"
       #   customer.credit_rating # => nil
       #
-      #   customer.credit_rating = "Average"
+      #   customer.credit_rating = 'Average'
       #   customer.credit_rating # => "Average"
       #
-      # And using the :admin role:
+      # And using the <tt>:admin</tt> role:
       #
       #   customer = Customer.new
-      #   customer.assign_attributes({ "name" => "David", "credit_rating" => "Excellent", :last_login => 1.day.ago }, :as => :admin)
+      #   customer.assign_attributes({ name: 'David', credit_rating: 'Excellent', last_login: 1.day.ago }, as: :admin)
       #   customer.name          # => "David"
       #   customer.credit_rating # => "Excellent"
       #
@@ -185,23 +189,131 @@ module ActiveModel
         self._active_authorizer = self._accessible_attributes
       end
 
+      # Returns an instance of <tt>ActiveModel::MassAssignmentSecurity::BlackList</tt>
+      # with the attributes protected by #attr_protected method. If no +role+
+      # is provided, then <tt>:default</tt> is used.
+      #
+      #   class Customer
+      #     include ActiveModel::MassAssignmentSecurity
+      #
+      #     attr_accessor :name, :email, :logins_count
+      #
+      #     attr_protected :logins_count
+      #     attr_protected :logins_count, :email, as: :admin
+      #   end
+      #
+      #   Customer.protected_attributes
+      #   # => #<ActiveModel::MassAssignmentSecurity::BlackList: {"logins_count"}>
+      #
+      #   Customer.protected_attributes(:default)
+      #   # => #<ActiveModel::MassAssignmentSecurity::BlackList: {"logins_count"}>
+      #
+      #   Customer.protected_attributes(:admin)
+      #   # => #<ActiveModel::MassAssignmentSecurity::BlackList: {"logins_count", "email"}>
       def protected_attributes(role = :default)
         protected_attributes_configs[role]
       end
 
+      # Returns an instance of <tt>ActiveModel::MassAssignmentSecurity::WhiteList</tt>
+      # with the attributes protected by #attr_accessible method. If no +role+
+      # is provided, then <tt>:default</tt> is used.
+      #
+      #   class Customer
+      #     include ActiveModel::MassAssignmentSecurity
+      #
+      #     attr_accessor :name, :credit_rating
+      #
+      #     attr_accessible :name, as: [:admin, :default]
+      #     attr_accessible :credit_rating, as: :admin
+      #   end
+      #
+      #   Customer.accessible_attributes
+      #   # => #<ActiveModel::MassAssignmentSecurity::WhiteList: {"name"}>
+      #
+      #   Customer.accessible_attributes(:default)
+      #   # => #<ActiveModel::MassAssignmentSecurity::WhiteList: {"name"}>
+      #
+      #   Customer.accessible_attributes(:admin)
+      #   # => #<ActiveModel::MassAssignmentSecurity::WhiteList: {"name", "credit_rating"}>
       def accessible_attributes(role = :default)
         accessible_attributes_configs[role]
       end
 
+      # Returns a hash with the protected attributes (by #attr_accessible or
+      # #attr_protected) per role.
+      #
+      #   class Customer
+      #     include ActiveModel::MassAssignmentSecurity
+      #
+      #     attr_accessor :name, :credit_rating
+      #
+      #     attr_accessible :name, as: [:admin, :default]
+      #     attr_accessible :credit_rating, as: :admin
+      #   end
+      #
+      #   Customer.active_authorizers
+      #   # => {
+      #   #       :admin=> #<ActiveModel::MassAssignmentSecurity::WhiteList: {"name", "credit_rating"}>,
+      #   #       :default=>#<ActiveModel::MassAssignmentSecurity::WhiteList: {"name"}>
+      #   #    }
       def active_authorizers
         self._active_authorizer ||= protected_attributes_configs
       end
       alias active_authorizer active_authorizers
 
+      # Returns an empty array by default. You can still override this to define
+      # the default attributes protected by #attr_protected method.
+      #
+      #   class Customer
+      #     include ActiveModel::MassAssignmentSecurity
+      #
+      #     def self.attributes_protected_by_default
+      #       [:name]
+      #     end
+      #   end
+      #
+      #   Customer.protected_attributes
+      #   # => #<ActiveModel::MassAssignmentSecurity::BlackList: {:name}>
       def attributes_protected_by_default
         []
       end
 
+      # Defines sanitize method.
+      #
+      #   class Customer
+      #     include ActiveModel::MassAssignmentSecurity
+      #
+      #     attr_accessor :name
+      #
+      #     attr_protected :name
+      #
+      #     def assign_attributes(values)
+      #       sanitize_for_mass_assignment(values).each do |k, v|
+      #         send("#{k}=", v)
+      #       end
+      #     end
+      #   end
+      #
+      #   # See ActiveModel::MassAssignmentSecurity::StrictSanitizer for more information.
+      #   Customer.mass_assignment_sanitizer = :strict
+      #
+      #   customer = Customer.new
+      #   customer.assign_attributes(name: 'David')
+      #   # => ActiveModel::MassAssignmentSecurity::Error: Can't mass-assign protected attributes for Customer: name
+      #
+      # Also, you can specify your own sanitizer object.
+      #
+      #   class CustomSanitizer < ActiveModel::MassAssignmentSecurity::Sanitizer
+      #     def process_removed_attributes(klass, attrs)
+      #       raise StandardError
+      #     end
+      #   end
+      #
+      #   Customer.mass_assignment_sanitizer = CustomSanitizer.new
+      #
+      #   customer = Customer.new
+      #   customer.assign_attributes(name: 'David')
+      #   # => StandardError: StandardError
       def mass_assignment_sanitizer=(value)
         self._mass_assignment_sanitizer = if value.is_a?(Symbol)
           const_get(:"#{value.to_s.camelize}Sanitizer").new(self)
@@ -227,11 +339,11 @@ module ActiveModel
 
   protected
 
-    def sanitize_for_mass_assignment(attributes, role = nil)
+    def sanitize_for_mass_assignment(attributes, role = nil) #:nodoc:
       _mass_assignment_sanitizer.sanitize(self.class, attributes, mass_assignment_authorizer(role))
     end
 
-    def mass_assignment_authorizer(role)
+    def mass_assignment_authorizer(role) #:nodoc:
       self.class.active_authorizer[role || :default]
     end
   end
diff --git a/activemodel/lib/active_model/mass_assignment_security/sanitizer.rb b/activemodel/lib/active_model/mass_assignment_security/sanitizer.rb
index 44ce5a489d..dafb7cdff3 100644
--- a/activemodel/lib/active_model/mass_assignment_security/sanitizer.rb
+++ b/activemodel/lib/active_model/mass_assignment_security/sanitizer.rb
@@ -1,6 +1,6 @@
 module ActiveModel
   module MassAssignmentSecurity
-    class Sanitizer
+    class Sanitizer #:nodoc:
       # Returns all attributes not denied by the authorizer.
       def sanitize(klass, attributes, authorizer)
         rejected = []
@@ -18,7 +18,7 @@ module ActiveModel
       end
     end
 
-    class LoggerSanitizer < Sanitizer
+    class LoggerSanitizer < Sanitizer #:nodoc:
       def initialize(target)
         @target = target
         super()
@@ -50,7 +50,7 @@ module ActiveModel
       end
     end
 
-    class StrictSanitizer < Sanitizer
+    class StrictSanitizer < Sanitizer #:nodoc:
       def initialize(target = nil)
         super()
       end
@@ -65,7 +65,7 @@ module ActiveModel
       end
     end
 
-    class Error < StandardError
+    class Error < StandardError #:nodoc:
       def initialize(klass, attrs)
         super("Can't mass-assign protected attributes for #{klass.name}: #{attrs.join(', ')}")
       end
diff --git a/activemodel/lib/active_model/naming.rb b/activemodel/lib/active_model/naming.rb
index af89391413..7ba439fb3e 100644
--- a/activemodel/lib/active_model/naming.rb
+++ b/activemodel/lib/active_model/naming.rb
@@ -218,6 +218,14 @@ module ActiveModel
     # Returns an ActiveModel::Name object for module. It can be
     # used to retrieve all kinds of naming-related information
     # (See ActiveModel::Name for more information).
+    #
+    #   class Person < ActiveModel::Model
+    #   end
+    #
+    #   Person.model_name          # => Person
+    #   Person.model_name.class    # => ActiveModel::Name
+    #   Person.model_name.singular # => "person"
+    #   Person.model_name.plural   # => "people"
     def model_name
       @_model_name ||= begin
         namespace = self.parents.detect do |n|
@@ -254,11 +262,11 @@ module ActiveModel
     # Returns string to use while generating route names. It differs for
     # namespaced models regarding whether it's inside isolated engine.
     #
-    # For isolated engine:
-    # ActiveModel::Naming.route_key(Blog::Post) #=> post
+    #   # For isolated engine:
+    #   ActiveModel::Naming.route_key(Blog::Post) #=> post
     #
-    # For shared engine:
-    # ActiveModel::Naming.route_key(Blog::Post) #=> blog_post
+    #   # For shared engine:
+    #   ActiveModel::Naming.route_key(Blog::Post) #=> blog_post
     def self.singular_route_key(record_or_class)
       model_name_from_record_or_class(record_or_class).singular_route_key
     end
@@ -266,11 +274,11 @@ module ActiveModel
     # Returns string to use while generating route names. It differs for
     # namespaced models regarding whether it's inside isolated engine.
     #
-    # For isolated engine:
-    # ActiveModel::Naming.route_key(Blog::Post) #=> posts
+    #   # For isolated engine:
+    #   ActiveModel::Naming.route_key(Blog::Post) #=> posts
     #
-    # For shared engine:
-    # ActiveModel::Naming.route_key(Blog::Post) #=> blog_posts
+    #   # For shared engine:
+    #   ActiveModel::Naming.route_key(Blog::Post) #=> blog_posts
     #
     # The route key also considers if the noun is uncountable and, in
     # such cases, automatically appends _index.
@@ -281,11 +289,11 @@ module ActiveModel
     # Returns string to use for params names. It differs for
     # namespaced models regarding whether it's inside isolated engine.
     #
-    # For isolated engine:
-    # ActiveModel::Naming.param_key(Blog::Post) #=> post
+    #   # For isolated engine:
+    #   ActiveModel::Naming.param_key(Blog::Post) #=> post
     #
-    # For shared engine:
-    # ActiveModel::Naming.param_key(Blog::Post) #=> blog_post
+    #   # For shared engine:
+    #   ActiveModel::Naming.param_key(Blog::Post) #=> blog_post
     def self.param_key(record_or_class)
       model_name_from_record_or_class(record_or_class).param_key
     end
diff --git a/activemodel/lib/active_model/observer_array.rb b/activemodel/lib/active_model/observer_array.rb
index 8de6918d18..77bc0f71e3 100644
--- a/activemodel/lib/active_model/observer_array.rb
+++ b/activemodel/lib/active_model/observer_array.rb
@@ -5,20 +5,21 @@ module ActiveModel
   # a particular model class.
   class ObserverArray < Array
     attr_reader :model_class
-    def initialize(model_class, *args)
+    def initialize(model_class, *args) #:nodoc:
       @model_class = model_class
       super(*args)
     end
 
-    # Returns true if the given observer is disabled for the model class.
-    def disabled_for?(observer)
+    # Returns +true+ if the given observer is disabled for the model class,
+    # +false+ otherwise.
+    def disabled_for?(observer) #:nodoc:
       disabled_observers.include?(observer.class)
     end
 
     # Disables one or more observers. This supports multiple forms:
     #
     #   ORM.observers.disable :all
-    #     # => disables all observers for all models subclassed from 
+    #     # => disables all observers for all models subclassed from
     #     #    an ORM base class that includes ActiveModel::Observing
     #     #    e.g. ActiveRecord::Base
     #
@@ -43,7 +44,7 @@ module ActiveModel
     # Enables one or more observers. This supports multiple forms:
     #
     #   ORM.observers.enable :all
-    #     # => enables all observers for all models subclassed from 
+    #     # => enables all observers for all models subclassed from
     #     #    an ORM base class that includes ActiveModel::Observing
     #     #    e.g. ActiveRecord::Base
     #
@@ -71,11 +72,11 @@ module ActiveModel
 
     protected
 
-      def disabled_observers
+      def disabled_observers #:nodoc:
         @disabled_observers ||= Set.new
       end
 
-      def observer_class_for(observer)
+      def observer_class_for(observer) #:nodoc:
         return observer if observer.is_a?(Class)
 
         if observer.respond_to?(:to_sym) # string/symbol
@@ -86,25 +87,25 @@ module ActiveModel
         end
       end
 
-      def start_transaction
+      def start_transaction #:nodoc:
         disabled_observer_stack.push(disabled_observers.dup)
         each_subclass_array do |array|
           array.start_transaction
         end
       end
 
-      def disabled_observer_stack
+      def disabled_observer_stack #:nodoc:
         @disabled_observer_stack ||= []
       end
 
-      def end_transaction
+      def end_transaction #:nodoc:
         @disabled_observers = disabled_observer_stack.pop
         each_subclass_array do |array|
           array.end_transaction
         end
       end
 
-      def transaction
+      def transaction #:nodoc:
         start_transaction
 
         begin
@@ -114,13 +115,13 @@ module ActiveModel
         end
       end
 
-      def each_subclass_array
+      def each_subclass_array #:nodoc:
         model_class.descendants.each do |subclass|
           yield subclass.observers
         end
       end
 
-      def set_enablement(enabled, observers)
+      def set_enablement(enabled, observers) #:nodoc:
         if block_given?
           transaction do
             set_enablement(enabled, observers)
diff --git a/activemodel/lib/active_model/observing.rb b/activemodel/lib/active_model/observing.rb
index acc96ddc9f..9db7639ea3 100644
--- a/activemodel/lib/active_model/observing.rb
+++ b/activemodel/lib/active_model/observing.rb
@@ -8,6 +8,7 @@ require 'active_support/core_ext/object/try'
 require 'active_support/descendants_tracker'
 
 module ActiveModel
+  # == Active Model Observers Activation
   module Observing
     extend ActiveSupport::Concern
 
@@ -16,9 +17,7 @@ module ActiveModel
     end
 
     module ClassMethods
-      # == Active Model Observers Activation
-      #
-      # Activates the observers assigned. Examples:
+      # Activates the observers assigned.
       #
       #   class ORM
       #     include ActiveModel::Observing
@@ -34,34 +33,95 @@ module ActiveModel
       #   ORM.observers = Cacher, GarbageCollector
       #
       # Note: Setting this does not instantiate the observers yet.
-      # +instantiate_observers+ is called during startup, and before
+      # <tt>instantiate_observers</tt> is called during startup, and before
       # each development request.
       def observers=(*values)
         observers.replace(values.flatten)
       end
 
-      # Gets an array of observers observing this model.
-      # The array also provides +enable+ and +disable+ methods
-      # that allow you to selectively enable and disable observers.
-      # (see <tt>ActiveModel::ObserverArray.enable</tt> and
-      # <tt>ActiveModel::ObserverArray.disable</tt> for more on this)
+      # Gets an array of observers observing this model. The array also provides
+      # +enable+ and +disable+ methods that allow you to selectively enable and
+      # disable observers (see ActiveModel::ObserverArray.enable and
+      # ActiveModel::ObserverArray.disable for more on this).
+      #
+      #   class ORM
+      #     include ActiveModel::Observing
+      #   end
+      #
+      #   ORM.observers = :cacher, :garbage_collector
+      #   ORM.observers       # => [:cacher, :garbage_collector]
+      #   ORM.observers.class # => ActiveModel::ObserverArray
       def observers
         @observers ||= ObserverArray.new(self)
       end
 
-      # Gets the current observer instances.
+      # Returns the current observer instances.
+      #
+      #   class Foo
+      #     include ActiveModel::Observing
+      #
+      #     attr_accessor :status
+      #   end
+      #
+      #   class FooObserver < ActiveModel::Observer
+      #     def on_spec(record, *args)
+      #       record.status = true
+      #     end
+      #   end
+      #
+      #   Foo.observers = FooObserver
+      #   Foo.instantiate_observers
+      #
+      #   Foo.observer_instances # => [#<FooObserver:0x007fc212c40820>]
       def observer_instances
         @observer_instances ||= []
       end
 
       # Instantiate the global observers.
+      #
+      #   class Foo
+      #     include ActiveModel::Observing
+      #
+      #     attr_accessor :status
+      #   end
+      #
+      #   class FooObserver < ActiveModel::Observer
+      #     def on_spec(record, *args)
+      #       record.status = true
+      #     end
+      #   end
+      #
+      #   Foo.observers = FooObserver
+      #
+      #   foo = Foo.new
+      #   foo.status = false
+      #   foo.notify_observers(:on_spec)
+      #   foo.status # => false
+      #
+      #   Foo.instantiate_observers # => [FooObserver]
+      #
+      #   foo = Foo.new
+      #   foo.status = false
+      #   foo.notify_observers(:on_spec)
+      #   foo.status # => true
       def instantiate_observers
         observers.each { |o| instantiate_observer(o) }
       end
 
-      # Add a new observer to the pool.
-      # The new observer needs to respond to 'update', otherwise it
-      # raises an +ArgumentError+ exception.
+      # Add a new observer to the pool. The new observer needs to respond to
+      # <tt>update</tt>, otherwise it raises an +ArgumentError+ exception.
+      #
+      #   class Foo
+      #     include ActiveModel::Observing
+      #   end
+      #
+      #   class FooObserver < ActiveModel::Observer
+      #   end
+      #
+      #   Foo.add_observer(FooObserver.instance)
+      #
+      #   Foo.observers_instance
+      #   # => [#<FooObserver:0x007fccf55d9390>]
       def add_observer(observer)
         unless observer.respond_to? :update
           raise ArgumentError, "observer needs to respond to 'update'"
@@ -69,16 +129,47 @@ module ActiveModel
         observer_instances << observer
       end
 
-      # Notify list of observers of a change.
+      # Fires notifications to model's observers.
+      #
+      #   def save
+      #     notify_observers(:before_save)
+      #     ...
+      #     notify_observers(:after_save)
+      #   end
+      #
+      # Custom notifications can be sent in a similar fashion:
+      #
+      #   notify_observers(:custom_notification, :foo)
+      #
+      # This will call <tt>custom_notification</tt>, passing as arguments
+      # the current object and <tt>:foo</tt>.
       def notify_observers(*args)
         observer_instances.each { |observer| observer.update(*args) }
       end
 
-      # Total number of observers.
+      # Returns the total number of instantiated observers.
+      #
+      #   class Foo
+      #     include ActiveModel::Observing
+      #
+      #     attr_accessor :status
+      #   end
+      #
+      #   class FooObserver < ActiveModel::Observer
+      #     def on_spec(record, *args)
+      #       record.status = true
+      #     end
+      #   end
+      #
+      #   Foo.observers = FooObserver
+      #   Foo.observers_count # => 0
+      #   Foo.instantiate_observers
+      #   Foo.observers_count # => 1
       def observers_count
         observer_instances.size
       end
 
+      # <tt>count_observers</tt> is deprecated. Use #observers_count.
       def count_observers
         msg = "count_observers is deprecated in favor of observers_count"
         ActiveSupport::Deprecation.warn(msg)
@@ -103,27 +194,36 @@ module ActiveModel
         end
 
         # Notify observers when the observed class is subclassed.
-        def inherited(subclass)
+        def inherited(subclass) #:nodoc:
           super
           notify_observers :observed_class_inherited, subclass
         end
     end
 
-    # Fires notifications to model's observers
+    # Notify a change to the list of observers.
+    #
+    #   class Foo
+    #     include ActiveModel::Observing
     #
-    #   def save
-    #     notify_observers(:before_save)
-    #     ...
-    #     notify_observers(:after_save)
+    #     attr_accessor :status
     #   end
     #
-    # Custom notifications can be sent in a similar fashion:
+    #   class FooObserver < ActiveModel::Observer
+    #     def on_spec(record, *args)
+    #       record.status = true
+    #     end
+    #   end
     #
-    #   notify_observers(:custom_notification, :foo)
+    #   Foo.observers = FooObserver
+    #   Foo.instantiate_observers # => [FooObserver]
     #
-    # This will call +custom_notification+, passing as arguments
-    # the current object and :foo.
+    #   foo = Foo.new
+    #   foo.status = false
+    #   foo.notify_observers(:on_spec)
+    #   foo.status # => true
     #
+    # See ActiveModel::Observing::ClassMethods.notify_observers for more
+    # information.
     def notify_observers(method, *extra_args)
       self.class.notify_observers(method, self, *extra_args)
     end
@@ -135,15 +235,15 @@ module ActiveModel
   # behavior outside the original class. This is a great way to reduce the
   # clutter that normally comes when the model class is burdened with
   # functionality that doesn't pertain to the core responsibility of the
-  # class. Example:
+  # class.
   #
   #   class CommentObserver < ActiveModel::Observer
   #     def after_save(comment)
-  #       Notifications.comment("admin@do.com", "New comment was posted", comment).deliver
+  #       Notifications.comment('admin@do.com', 'New comment was posted', comment).deliver
   #     end
   #   end
   #
-  # This Observer sends an email when a Comment#save is finished.
+  # This Observer sends an email when a <tt>Comment#save</tt> is finished.
   #
   #   class ContactObserver < ActiveModel::Observer
   #     def after_create(contact)
@@ -160,44 +260,50 @@ module ActiveModel
   # == Observing a class that can't be inferred
   #
   # Observers will by default be mapped to the class with which they share a
-  # name. So CommentObserver will be tied to observing Comment, ProductManagerObserver
-  # to ProductManager, and so on. If you want to name your observer differently than
-  # the class you're interested in observing, you can use the <tt>Observer.observe</tt>
-  # class method which takes either the concrete class (Product) or a symbol for that
-  # class (:product):
+  # name. So <tt>CommentObserver</tt> will be tied to observing <tt>Comment</tt>,
+  # <tt>ProductManagerObserver</tt> to <tt>ProductManager</tt>, and so on. If
+  # you want to name your observer differently than the class you're interested
+  # in observing, you can use the <tt>Observer.observe</tt> class method which
+  # takes either the concrete class (<tt>Product</tt>) or a symbol for that
+  # class (<tt>:product</tt>):
   #
   #   class AuditObserver < ActiveModel::Observer
   #     observe :account
   #
   #     def after_update(account)
-  #       AuditTrail.new(account, "UPDATED")
+  #       AuditTrail.new(account, 'UPDATED')
   #     end
   #   end
   #
-  # If the audit observer needs to watch more than one kind of object, this can be
-  # specified with multiple arguments:
+  # If the audit observer needs to watch more than one kind of object, this can
+  # be specified with multiple arguments:
   #
   #   class AuditObserver < ActiveModel::Observer
   #     observe :account, :balance
   #
   #     def after_update(record)
-  #       AuditTrail.new(record, "UPDATED")
+  #       AuditTrail.new(record, 'UPDATED')
   #     end
   #   end
   #
-  # The AuditObserver will now act on both updates to Account and Balance by treating
-  # them both as records.
+  # The <tt>AuditObserver</tt> will now act on both updates to <tt>Account</tt>
+  # and <tt>Balance</tt> by treating them both as records.
   #
-  # If you're using an Observer in a Rails application with Active Record, be sure to
-  # read about the necessary configuration in the documentation for
+  # If you're using an Observer in a Rails application with Active Record, be
+  # sure to read about the necessary configuration in the documentation for
   # ActiveRecord::Observer.
-  #
   class Observer
     include Singleton
     extend ActiveSupport::DescendantsTracker
 
     class << self
       # Attaches the observer to the supplied model classes.
+      #
+      #   class AuditObserver < ActiveModel::Observer
+      #     observe :account, :balance
+      #   end
+      #
+      #   AuditObserver.observed_classes # => [Account, Balance]
       def observe(*models)
         models.flatten!
         models.collect! { |model| model.respond_to?(:to_sym) ? model.to_s.camelize.constantize : model }
@@ -206,6 +312,8 @@ module ActiveModel
 
       # Returns an array of Classes to observe.
       #
+      #   AccountObserver.observed_classes # => [Account]
+      #
       # You can override this instead of using the +observe+ helper.
       #
       #   class AuditObserver < ActiveModel::Observer
@@ -217,8 +325,11 @@ module ActiveModel
         Array(observed_class)
       end
 
-      # The class observed by default is inferred from the observer's class name:
-      #   assert_equal Person, PersonObserver.observed_class
+      # Returns the class observed by default. It's inferred from the observer's
+      # class name.
+      #
+      #   PersonObserver.observed_class  # => Person
+      #   AccountObserver.observed_class # => Account
       def observed_class
         name[/(.*)Observer/, 1].try :constantize
       end
@@ -226,7 +337,7 @@ module ActiveModel
 
     # Start observing the declared classes and their subclasses.
     # Called automatically by the instance method.
-    def initialize
+    def initialize #:nodoc:
       observed_classes.each { |klass| add_observer!(klass) }
     end
 
@@ -237,7 +348,7 @@ module ActiveModel
     # Send observed_method(object) if the method exists and
     # the observer is enabled for the given object's class.
     def update(observed_method, object, *extra_args, &block) #:nodoc:
-      return if !respond_to?(observed_method) || disabled_for?(object) 
+      return if !respond_to?(observed_method) || disabled_for?(object)
       send(observed_method, object, *extra_args, &block)
     end
 
@@ -254,7 +365,7 @@ module ActiveModel
       end
 
       # Returns true if notifications are disabled for this object.
-      def disabled_for?(object)
+      def disabled_for?(object) #:nodoc:
         klass = object.class
         return false unless klass.respond_to?(:observers)
         klass.observers.disabled_for?(self)
diff --git a/activemodel/lib/active_model/secure_password.rb b/activemodel/lib/active_model/secure_password.rb
index dc89efd2d1..d011402081 100644
--- a/activemodel/lib/active_model/secure_password.rb
+++ b/activemodel/lib/active_model/secure_password.rb
@@ -6,12 +6,12 @@ module ActiveModel
       # Adds methods to set and authenticate against a BCrypt password.
       # This mechanism requires you to have a password_digest attribute.
       #
-      # Validations for presence of password on create, confirmation of password (using
-      # a "password_confirmation" attribute) are automatically added.
-      # If you wish to turn off validations, pass 'validations: false' as an argument.
-      # You can add more validations by hand if need be.
+      # Validations for presence of password on create, confirmation of password
+      # (using a +password_confirmation+ attribute) are automatically added. If
+      # you wish to turn off validations, pass <tt>validations: false</tt> as an
+      # argument. You can add more validations by hand if need be.
       #
-      # You need to add bcrypt-ruby (~> 3.0.0) to Gemfile to use has_secure_password:
+      # You need to add bcrypt-ruby (~> 3.0.0) to Gemfile to use #has_secure_password:
       #
       #   gem 'bcrypt-ruby', '~> 3.0.0'
       #
@@ -22,24 +22,25 @@ module ActiveModel
       #     has_secure_password
       #   end
       #
-      #   user = User.new(:name => "david", :password => "", :password_confirmation => "nomatch")
+      #   user = User.new(name: 'david', password: '', password_confirmation: 'nomatch')
       #   user.save                                                      # => false, password required
-      #   user.password = "mUc3m00RsqyRe"
+      #   user.password = 'mUc3m00RsqyRe'
       #   user.save                                                      # => false, confirmation doesn't match
-      #   user.password_confirmation = "mUc3m00RsqyRe"
+      #   user.password_confirmation = 'mUc3m00RsqyRe'
       #   user.save                                                      # => true
-      #   user.authenticate("notright")                                  # => false
-      #   user.authenticate("mUc3m00RsqyRe")                             # => user
-      #   User.find_by_name("david").try(:authenticate, "notright")      # => false
-      #   User.find_by_name("david").try(:authenticate, "mUc3m00RsqyRe") # => user
+      #   user.authenticate('notright')                                  # => false
+      #   user.authenticate('mUc3m00RsqyRe')                             # => user
+      #   User.find_by_name('david').try(:authenticate, 'notright')      # => false
+      #   User.find_by_name('david').try(:authenticate, 'mUc3m00RsqyRe') # => user
       def has_secure_password(options = {})
         # Load bcrypt-ruby only when has_secure_password is used.
-        # This is to avoid ActiveModel (and by extension the entire framework) being dependent on a binary library.
+        # This is to avoid ActiveModel (and by extension the entire framework)
+        # being dependent on a binary library.
         gem 'bcrypt-ruby', '~> 3.0.0'
         require 'bcrypt'
 
         attr_reader :password
-        
+
         if options.fetch(:validations, true)
           validates_confirmation_of :password
           validates_presence_of     :password, :on => :create
@@ -50,7 +51,7 @@ module ActiveModel
         include InstanceMethodsOnActivation
 
         if respond_to?(:attributes_protected_by_default)
-          def self.attributes_protected_by_default
+          def self.attributes_protected_by_default #:nodoc:
             super + ['password_digest']
           end
         end
@@ -58,13 +59,32 @@ module ActiveModel
     end
 
     module InstanceMethodsOnActivation
-      # Returns self if the password is correct, otherwise false.
+      # Returns +self+ if the password is correct, otherwise +false+.
+      #
+      #   class User < ActiveRecord::Base
+      #     has_secure_password validations: false
+      #   end
+      #
+      #   user = User.new(name: 'david', password: 'mUc3m00RsqyRe')
+      #   user.save
+      #   user.authenticate('notright')      # => false
+      #   user.authenticate('mUc3m00RsqyRe') # => user
       def authenticate(unencrypted_password)
         BCrypt::Password.new(password_digest) == unencrypted_password && self
       end
 
-      # Encrypts the password into the password_digest attribute, only if the
+      # Encrypts the password into the +password_digest+ attribute, only if the
       # new password is not blank.
+      #
+      #   class User < ActiveRecord::Base
+      #     has_secure_password validations: false
+      #   end
+      #
+      #   user = User.new
+      #   user.password = nil
+      #   user.password_digest # => nil
+      #   user.password = 'mUc3m00RsqyRe'
+      #   user.password_digest # => "$2a$10$4LEA7r4YmNHtvlAvHhsYAeZmk/xeUVtMTYqwIvYY76EW5GUqDiP4."
       def password=(unencrypted_password)
         unless unencrypted_password.blank?
           @password = unencrypted_password
diff --git a/activemodel/lib/active_model/serializers/json.rb b/activemodel/lib/active_model/serializers/json.rb
index eaea0475ad..a4252b995d 100644
--- a/activemodel/lib/active_model/serializers/json.rb
+++ b/activemodel/lib/active_model/serializers/json.rb
@@ -18,8 +18,8 @@ module ActiveModel
       # passed through +options+.
       #
       # The option <tt>include_root_in_json</tt> controls the top-level behavior
-      # of +as_json+. If true +as_json+ will emit a single root node named after
-      # the object's type. The default value for <tt>include_root_in_json</tt>
+      # of +as_json+. If +true+, +as_json+ will emit a single root node named
+      # after the object's type. The default value for <tt>include_root_in_json</tt>
       # option is +false+.
       #
       #   user = User.find(1)
@@ -100,6 +100,40 @@ module ActiveModel
         end
       end
 
+      # Sets the model +attributes+ from a JSON string. Returns +self+.
+      #
+      #   class Person
+      #     include ActiveModel::Serializers::JSON
+      #
+      #     attr_accessor :name, :age, :awesome
+      #
+      #     def attributes=(hash)
+      #       hash.each do |key, value|
+      #         instance_variable_set("@#{key}", value)
+      #       end
+      #     end
+      #
+      #     def attributes
+      #       instance_values
+      #     end
+      #   end
+      #
+      #   json = { name: 'bob', age: 22, awesome:true }.to_json
+      #   person = Person.new
+      #   person.from_json(json) # => #<Person:0x007fec5e7a0088 @age=22, @awesome=true, @name="bob">
+      #   person.name            # => "bob"
+      #   person.age             # => 22
+      #   person.awesome         # => true
+      #
+      # The default value for +include_root+ is +false+. You can change it to
+      # +true+ if the given JSON string includes a single root node.
+      #
+      #   json = { person: { name: 'bob', age: 22, awesome:true } }.to_json
+      #   person = Person.new
+      #   person.from_json(json) # => #<Person:0x007fec5e7a0088 @age=22, @awesome=true, @name="bob">
+      #   person.name            # => "bob"
+      #   person.age             # => 22
+      #   person.awesome         # => true
       def from_json(json, include_root=include_root_in_json)
         hash = ActiveSupport::JSON.decode(json)
         hash = hash.values.first if include_root
diff --git a/activemodel/lib/active_model/serializers/xml.rb b/activemodel/lib/active_model/serializers/xml.rb
index 2b3e9ce134..016d821fdf 100644
--- a/activemodel/lib/active_model/serializers/xml.rb
+++ b/activemodel/lib/active_model/serializers/xml.rb
@@ -110,7 +110,7 @@ module ActiveModel
           end
         end
 
-        # TODO This can likely be cleaned up to simple use ActiveSupport::XmlMini.to_tag as well.
+        # TODO: This can likely be cleaned up to simple use ActiveSupport::XmlMini.to_tag as well.
         def add_associations(association, records, opts)
           merged_options = opts.merge(options.slice(:builder, :indent))
           merged_options[:skip_instruct] = true
@@ -161,8 +161,8 @@ module ActiveModel
       # Returns XML representing the model. Configuration can be
       # passed through +options+.
       #
-      # Without any +options+, the returned XML string will include all the model's
-      # attributes. For example:
+      # Without any +options+, the returned XML string will include all the
+      # model's attributes.
       #
       #   user = User.find(1)
       #   user.to_xml
@@ -175,18 +175,42 @@ module ActiveModel
       #     <created-at type="dateTime">2011-01-30T22:29:23Z</created-at>
       #   </user>
       #
-      # The <tt>:only</tt> and <tt>:except</tt> options can be used to limit the attributes
-      # included, and work similar to the +attributes+ method.
+      # The <tt>:only</tt> and <tt>:except</tt> options can be used to limit the
+      # attributes included, and work similar to the +attributes+ method.
       #
       # To include the result of some method calls on the model use <tt>:methods</tt>.
       #
       # To include associations use <tt>:include</tt>.
       #
-      # For further documentation see activerecord/lib/active_record/serializers/xml_serializer.xml.
+      # For further documentation, see <tt>ActiveRecord::Serialization#to_xml</tt>
       def to_xml(options = {}, &block)
         Serializer.new(self, options).serialize(&block)
       end
 
+      # Sets the model +attributes+ from a JSON string. Returns +self+.
+      #
+      #   class Person
+      #     include ActiveModel::Serializers::Xml
+      #
+      #     attr_accessor :name, :age, :awesome
+      #
+      #     def attributes=(hash)
+      #       hash.each do |key, value|
+      #         instance_variable_set("@#{key}", value)
+      #       end
+      #     end
+      #
+      #     def attributes
+      #       instance_values
+      #     end
+      #   end
+      #
+      #   xml = { name: 'bob', age: 22, awesome:true }.to_xml
+      #   person = Person.new
+      #   person.from_xml(xml) # => #<Person:0x007fec5e3b3c40 @age=22, @awesome=true, @name="bob">
+      #   person.name          # => "bob"
+      #   person.age           # => 22
+      #   person.awesome       # => true
       def from_xml(xml)
         self.attributes = Hash.from_xml(xml).values.first
         self
diff --git a/activemodel/lib/active_model/validations.rb b/activemodel/lib/active_model/validations.rb
index 5ae3a97c6b..4762f39044 100644
--- a/activemodel/lib/active_model/validations.rb
+++ b/activemodel/lib/active_model/validations.rb
@@ -32,11 +32,11 @@ module ActiveModel
   #   person.first_name = 'zoolander'
   #   person.valid?                   # => false
   #   person.invalid?                 # => true
-  #   person.errors                   # => #<Hash {:first_name=>["starts with z."]}>
+  #   person.errors.messages          # => {:first_name=>["starts with z."]}
   #
-  # Note that <tt>ActiveModel::Validations</tt> automatically adds an +errors+ method
-  # to your instances initialized with a new <tt>ActiveModel::Errors</tt> object, so
-  # there is no need for you to do this manually.
+  # Note that <tt>ActiveModel::Validations</tt> automatically adds an +errors+
+  # method to your instances initialized with a new <tt>ActiveModel::Errors</tt>
+  # object, so there is no need for you to do this manually.
   module Validations
     extend ActiveSupport::Concern
 
@@ -62,24 +62,25 @@ module ActiveModel
       #
       #     attr_accessor :first_name, :last_name
       #
-      #     validates_each :first_name, :last_name, :allow_blank => true do |record, attr, value|
+      #     validates_each :first_name, :last_name, allow_blank: true do |record, attr, value|
       #       record.errors.add attr, 'starts with z.' if value.to_s[0] == ?z
       #     end
       #   end
       #
       # Options:
       # * <tt>:on</tt> - Specifies the context where this validation is active
-      #   (e.g. <tt>:on => :create</tt> or <tt>:on => :custom_validation_context</tt>)
+      #   (e.g. <tt>on: :create</tt> or <tt>on: :custom_validation_context</tt>)
       # * <tt>:allow_nil</tt> - Skip validation if attribute is +nil+.
       # * <tt>:allow_blank</tt> - Skip validation if attribute is blank.
       # * <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 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.
       def validates_each(*attr_names, &block)
         validates_with BlockValidator, _merge_attributes(attr_names), &block
       end
@@ -96,7 +97,7 @@ module ActiveModel
       #     validate :must_be_friends
       #
       #     def must_be_friends
-      #       errors.add(:base, "Must be friends to leave a comment") unless commenter.friend_of?(commentee)
+      #       errors.add(:base, 'Must be friends to leave a comment') unless commenter.friend_of?(commentee)
       #     end
       #   end
       #
@@ -110,7 +111,7 @@ module ActiveModel
       #     end
       #
       #     def must_be_friends
-      #       errors.add(:base, "Must be friends to leave a comment") unless commenter.friend_of?(commentee)
+      #       errors.add(:base, 'Must be friends to leave a comment') unless commenter.friend_of?(commentee)
       #     end
       #   end
       #
@@ -120,23 +121,24 @@ module ActiveModel
       #     include ActiveModel::Validations
       #
       #     validate do
-      #       errors.add(:base, "Must be friends to leave a comment") unless commenter.friend_of?(commentee)
+      #       errors.add(:base, 'Must be friends to leave a comment') unless commenter.friend_of?(commentee)
       #     end
       #   end
       #
       # Options:
       # * <tt>:on</tt> - Specifies the context where this validation is active
-      #   (e.g. <tt>:on => :create</tt> or <tt>:on => :custom_validation_context</tt>)
+      #   (e.g. <tt>on: :create</tt> or <tt>on: :custom_validation_context</tt>)
       # * <tt>:allow_nil</tt> - Skip validation if attribute is +nil+.
       # * <tt>:allow_blank</tt> - Skip validation if attribute is blank.
       # * <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 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.
       def validate(*args, &block)
         options = args.extract_options!
         if options.key?(:on)
@@ -170,39 +172,101 @@ module ActiveModel
       end
 
       # List all validators that are being used to validate a specific attribute.
+      #
+      #   class Person
+      #     include ActiveModel::Validations
+      #
+      #     attr_accessor :name , :age
+      #
+      #     validates_presence_of :name
+      #     validates_inclusion_of :age, in: 0..99
+      #   end
+      #
+      #   Person.validators_on(:name)
+      #   # => [
+      #   #       #<ActiveModel::Validations::PresenceValidator:0x007fe604914e60 @attributes=[:name], @options={}>,
+      #   #       #<ActiveModel::Validations::InclusionValidator:0x007fe603bb8780 @attributes=[:age], @options={:in=>0..99}>
+      #   #    ]
       def validators_on(*attributes)
         attributes.map do |attribute|
           _validators[attribute.to_sym]
         end.flatten
       end
 
-      # Check if method is an attribute method or not.
+      # Returns +true+ if +attribute+ is an attribute method, +false+ otherwise.
+      #
+      #  class Person
+      #    include ActiveModel::Validations
+      #
+      #    attr_accessor :name
+      #  end
+      #
+      #  User.attribute_method?(:name) # => true
+      #  User.attribute_method?(:age)  # => false
       def attribute_method?(attribute)
         method_defined?(attribute)
       end
 
       # Copy validators on inheritance.
-      def inherited(base)
+      def inherited(base) #:nodoc:
         dup = _validators.dup
         base._validators = dup.each { |k, v| dup[k] = v.dup }
         super
       end
     end
 
-    # Clean the +Errors+ object if instance is duped
-    def initialize_dup(other) # :nodoc:
+    # Clean the +Errors+ object if instance is duped.
+    def initialize_dup(other) #:nodoc:
       @errors = nil
       super
     end
 
-    # Returns the +Errors+ object that holds all information about attribute error messages.
+    # Returns the +Errors+ object that holds all information about attribute
+    # error messages.
+    #
+    #   class Person
+    #     include ActiveModel::Validations
+    #
+    #     attr_accessor :name
+    #     validates_presence_of :name
+    #   end
+    #
+    #   person = Person.new
+    #   person.valid? # => false
+    #   person.errors # => #<ActiveModel::Errors:0x007fe603816640 @messages={:name=>["can't be blank"]}>
     def errors
       @errors ||= Errors.new(self)
     end
 
-    # Runs all the specified validations and returns true if no errors were added
-    # otherwise false. Context can optionally be supplied to define which callbacks
-    # to test against (the context is defined on the validations using :on).
+    # Runs all the specified validations and returns +true+ if no errors were
+    # added otherwise +false+.
+    #
+    #   class Person
+    #     include ActiveModel::Validations
+    #
+    #     attr_accessor :name
+    #     validates_presence_of :name
+    #   end
+    #
+    #   person = Person.new
+    #   person.name = ''
+    #   person.valid? # => false
+    #   person.name = 'david'
+    #   person.valid? # => true
+    #
+    # Context can optionally be supplied to define which callbacks to test
+    # against (the context is defined on the validations using <tt>:on</tt>).
+    #
+    #   class Person
+    #     include ActiveModel::Validations
+    #
+    #     attr_accessor :name
+    #     validates_presence_of :name, on: :new
+    #   end
+    #
+    #   person = Person.new
+    #   person.valid?       # => true
+    #   person.valid?(:new) # => false
     def valid?(context = nil)
       current_context, self.validation_context = validation_context, context
       errors.clear
@@ -211,8 +275,35 @@ module ActiveModel
       self.validation_context = current_context
     end
 
-    # Performs the opposite of <tt>valid?</tt>. Returns true if errors were added,
-    # false otherwise.
+    # Performs the opposite of <tt>valid?</tt>. Returns +true+ if errors were
+    # added, +false+ otherwise.
+    #
+    #   class Person
+    #     include ActiveModel::Validations
+    #
+    #     attr_accessor :name
+    #     validates_presence_of :name
+    #   end
+    #
+    #   person = Person.new
+    #   person.name = ''
+    #   person.invalid? # => true
+    #   person.name = 'david'
+    #   person.invalid? # => false
+    #
+    # Context can optionally be supplied to define which callbacks to test
+    # against (the context is defined on the validations using <tt>:on</tt>).
+    #
+    #   class Person
+    #     include ActiveModel::Validations
+    #
+    #     attr_accessor :name
+    #     validates_presence_of :name, on: :new
+    #   end
+    #
+    #   person = Person.new
+    #   person.invalid?       # => false
+    #   person.invalid?(:new) # => true
     def invalid?(context = nil)
       !valid?(context)
     end
@@ -237,7 +328,7 @@ module ActiveModel
 
   protected
 
-    def run_validations!
+    def run_validations! #:nodoc:
       run_callbacks :validate
       errors.empty?
     end
diff --git a/activemodel/lib/active_model/validations/callbacks.rb b/activemodel/lib/active_model/validations/callbacks.rb
index dbafd0bd1a..bf3fe7ff04 100644
--- a/activemodel/lib/active_model/validations/callbacks.rb
+++ b/activemodel/lib/active_model/validations/callbacks.rb
@@ -2,24 +2,24 @@ require 'active_support/callbacks'
 
 module ActiveModel
   module Validations
+    # == Active Model Validation callbacks
+    #
+    # Provides an interface for any class to have +before_validation+ and
+    # +after_validation+ callbacks.
+    #
+    # First, include ActiveModel::Validations::Callbacks from the class you are
+    # creating:
+    #
+    #   class MyModel
+    #     include ActiveModel::Validations::Callbacks
+    #
+    #     before_validation :do_stuff_before_validation
+    #     after_validation  :do_stuff_after_validation
+    #   end
+    #
+    # Like other <tt>before_*</tt> callbacks if +before_validation+ returns
+    # +false+ then <tt>valid?</tt> will not be called.
     module Callbacks
-      # == Active Model Validation callbacks
-      #
-      # Provides an interface for any class to have <tt>before_validation</tt> and
-      # <tt>after_validation</tt> callbacks.
-      #
-      # First, include ActiveModel::Validations::Callbacks from the class you are
-      # creating:
-      #
-      #   class MyModel
-      #     include ActiveModel::Validations::Callbacks
-      #
-      #     before_validation :do_stuff_before_validation
-      #     after_validation  :do_stuff_after_validation
-      #   end
-      #
-      #   Like other before_* callbacks if <tt>before_validation</tt> returns false
-      #   then <tt>valid?</tt> will not be called.
       extend ActiveSupport::Concern
 
       included do
@@ -28,6 +28,30 @@ module ActiveModel
       end
 
       module ClassMethods
+        # Defines a callback that will get called right before validation
+        # happens.
+        #
+        #   class Person
+        #     include ActiveModel::Validations
+        #     include ActiveModel::Validations::Callbacks
+        #
+        #     attr_accessor :name
+        #
+        #     validates_length_of :name, maximum: 6
+        #
+        #     before_validation :remove_whitespaces
+        #
+        #     private
+        #
+        #     def remove_whitespaces
+        #       name.strip!
+        #     end
+        #   end
+        #
+        #   person = Person.new
+        #   person.name = '  bob  '
+        #   person.valid? # => true
+        #   person.name   # => "bob"
         def before_validation(*args, &block)
           options = args.last
           if options.is_a?(Hash) && options[:on]
@@ -37,6 +61,33 @@ module ActiveModel
           set_callback(:validation, :before, *args, &block)
         end
 
+        # Defines a callback that will get called right after validation
+        # happens.
+        #
+        #   class Person
+        #     include ActiveModel::Validations
+        #     include ActiveModel::Validations::Callbacks
+        #
+        #     attr_accessor :name, :status
+        #
+        #     validates_presence_of :name
+        #
+        #     after_validation :set_status
+        #
+        #     private
+        #
+        #     def set_status
+        #       self.status = errors.empty?
+        #     end
+        #   end
+        #
+        #   person = Person.new
+        #   person.name = ''
+        #   person.valid? # => false
+        #   person.status # => false
+        #   person.name = 'bob'
+        #   person.valid? # => true
+        #   person.status # => true
         def after_validation(*args, &block)
           options = args.extract_options!
           options[:prepend] = true
@@ -49,7 +100,7 @@ module ActiveModel
     protected
 
       # Overwrite run validations to include callbacks.
-      def run_validations!
+      def run_validations! #:nodoc:
         run_callbacks(:validation) { super }
       end
     end
diff --git a/activemodel/lib/active_model/validations/validates.rb b/activemodel/lib/active_model/validations/validates.rb
index ecda9dffcf..5892ad29d1 100644
--- a/activemodel/lib/active_model/validations/validates.rb
+++ b/activemodel/lib/active_model/validations/validates.rb
@@ -11,18 +11,18 @@ module ActiveModel
       #
       # Examples of using the default rails validators:
       #
-      #   validates :terms, :acceptance => true
-      #   validates :password, :confirmation => true
-      #   validates :username, :exclusion => { :in => %w(admin superuser) }
-      #   validates :email, :format => { :with => /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\Z/i, :on => :create }
-      #   validates :age, :inclusion => { :in => 0..9 }
-      #   validates :first_name, :length => { :maximum => 30 }
-      #   validates :age, :numericality => true
-      #   validates :username, :presence => true
-      #   validates :username, :uniqueness => true
+      #   validates :terms, acceptance: true
+      #   validates :password, confirmation: true
+      #   validates :username, exclusion: { in: %w(admin superuser) }
+      #   validates :email, format: { with: /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\Z/i, on: :create }
+      #   validates :age, inclusion: { in: 0..9 }
+      #   validates :first_name, length: { maximum: 30 }
+      #   validates :age, numericality: true
+      #   validates :username, presence: true
+      #   validates :username, uniqueness: true
       #
       # The power of the +validates+ method comes when using custom validators
-      # and default validators in one call for a given attribute e.g.
+      # and default validators in one call for a given attribute.
       #
       #   class EmailValidator < ActiveModel::EachValidator
       #     def validate_each(record, attribute, value)
@@ -35,12 +35,12 @@ module ActiveModel
       #     include ActiveModel::Validations
       #     attr_accessor :name, :email
       #
-      #     validates :name, :presence => true, :uniqueness => true, :length => { :maximum => 100 }
-      #     validates :email, :presence => true, :email => true
+      #     validates :name, presence: true, uniqueness: true, length: { maximum: 100 }
+      #     validates :email, presence: true, email: true
       #   end
       #
       # Validator classes may also exist within the class being validated
-      # allowing custom modules of validators to be included as needed e.g.
+      # allowing custom modules of validators to be included as needed.
       #
       #   class Film
       #     include ActiveModel::Validations
@@ -51,25 +51,27 @@ module ActiveModel
       #       end
       #     end
       #
-      #     validates :name, :title => true
+      #     validates :name, title: true
       #   end
       #
-      # Additionally validator classes may be in another namespace and still used within any class.
+      # Additionally validator classes may be in another namespace and still
+      # used within any class.
       #
       #   validates :name, :'film/title' => true
       #
-      # The validators hash can also handle regular expressions, ranges,
-      # arrays and strings in shortcut form, e.g.
+      # The validators hash can also handle regular expressions, ranges, arrays
+      # and strings in shortcut form.
       #
-      #   validates :email, :format => /@/
-      #   validates :gender, :inclusion => %w(male female)
-      #   validates :password, :length => 6..20
+      #   validates :email, format: /@/
+      #   validates :gender, inclusion: %w(male female)
+      #   validates :password, length: 6..20
       #
       # When using shortcut form, ranges and arrays are passed to your
-      # validator's initializer as +options[:in]+ while other types including
-      # regular expressions and strings are passed as +options[:with]+
+      # validator's initializer as <tt>options[:in]</tt> while other types
+      # including regular expressions and strings are passed as <tt>options[:with]</tt>.
       #
       # There is also a list of options that could be used along with validators:
+      #
       # * <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>.
@@ -87,14 +89,12 @@ module ActiveModel
       #
       # Example:
       #
-      #   validates :password, :presence => true, :confirmation => true, :if => :password_required?
-      #
-      # Finally, the options +:if+, +:unless+, +:on+, +:allow_blank+, +:allow_nil+ and +:strict+
-      # can be given to one specific validator, as a hash:
-      #
-      #   validates :password, :presence => { :if => :password_required? }, :confirmation => true
+      #   validates :password, presence: true, confirmation: true, if: :password_required?
       #
+      # Finally, the options +:if+, +:unless+, +:on+, +:allow_blank+, +:allow_nil+
+      # and +:strict+ can be given to one specific validator, as a hash:
       #
+      #   validates :password, presence: { if: :password_required? }, confirmation: true
       def validates(*attributes)
         defaults = attributes.extract_options!.dup
         validations = defaults.slice!(*_validates_default_keys)
@@ -122,8 +122,20 @@ module ActiveModel
       # users and are considered exceptional. So each validator defined with bang
       # or <tt>:strict</tt> option set to <tt>true</tt> will always raise
       # <tt>ActiveModel::StrictValidationFailed</tt> instead of adding error
-      # when validation fails.
-      # See <tt>validates</tt> for more information about the validation itself.
+      # when validation fails. See <tt>validates</tt> for more information about
+      # the validation itself.
+      #
+      #   class Person
+      #     include ActiveModel::Validations
+      #
+      #     attr_accessor :name
+      #     validates! :name, presence: true
+      #   end
+      #
+      #   person = Person.new
+      #   person.name = ''
+      #   person.valid?
+      #   # => ActiveModel::StrictValidationFailed: Name can't be blank
       def validates!(*attributes)
         options = attributes.extract_options!
         options[:strict] = true
@@ -134,7 +146,7 @@ module ActiveModel
 
       # When creating custom validators, it might be useful to be able to specify
       # additional default keys. This can be done by overwriting this method.
-      def _validates_default_keys
+      def _validates_default_keys #:nodoc:
         [:if, :unless, :on, :allow_blank, :allow_nil , :strict]
       end
 
diff --git a/activemodel/lib/active_model/validations/with.rb b/activemodel/lib/active_model/validations/with.rb
index 3c516f8b22..869591cd9e 100644
--- a/activemodel/lib/active_model/validations/with.rb
+++ b/activemodel/lib/active_model/validations/with.rb
@@ -34,7 +34,7 @@ module ActiveModel
       #   class MyValidator < ActiveModel::Validator
       #     def validate(record)
       #       if some_complex_logic
-      #         record.errors.add :base, "This record is invalid"
+      #         record.errors.add :base, 'This record is invalid'
       #       end
       #     end
       #
@@ -48,30 +48,32 @@ module ActiveModel
       #
       #   class Person
       #     include ActiveModel::Validations
-      #     validates_with MyValidator, MyOtherValidator, :on => :create
+      #     validates_with MyValidator, MyOtherValidator, on: :create
       #   end
       #
       # Configuration options:
       # * <tt>:on</tt> - Specifies when this validation is active
-      #   (<tt>:create</tt> or <tt>:update</tt>
+      #   (<tt>:create</tt> or <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.
+      #   (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.
       #
       # If you pass any additional configuration options, they will be passed
-      # to the class and available as <tt>options</tt>:
+      # to the class and available as +options+:
       #
       #   class Person
       #     include ActiveModel::Validations
-      #     validates_with MyValidator, :my_custom_key => "my custom value"
+      #     validates_with MyValidator, my_custom_key: 'my custom value'
       #   end
       #
       #   class MyValidator < ActiveModel::Validator
@@ -119,17 +121,17 @@ module ActiveModel
     #   class Person
     #     include ActiveModel::Validations
     #
-    #     validate :instance_validations, :on => :create
+    #     validate :instance_validations, on: :create
     #
     #     def instance_validations
     #       validates_with MyValidator, MyOtherValidator
     #     end
     #   end
     #
-    # Standard configuration options (:on, :if and :unless), which are
-    # available on the class version of +validates_with+, should instead be
-    # placed on the +validates+ method as these are applied and tested
-    # in the callback.
+    # Standard configuration options (<tt>:on</tt>, <tt>:if</tt> and
+    # <tt>:unless</tt>), which are available on the class version of
+    # +validates_with+, should instead be placed on the +validates+ method
+    # as these are applied and tested in the callback.
     #
     # If you pass any additional configuration options, they will be passed
     # to the class and available as +options+, please refer to the
diff --git a/activemodel/lib/active_model/validator.rb b/activemodel/lib/active_model/validator.rb
index cbbf58505b..87e4319421 100644
--- a/activemodel/lib/active_model/validator.rb
+++ b/activemodel/lib/active_model/validator.rb
@@ -1,6 +1,6 @@
 require "active_support/core_ext/module/anonymous"
 
-module ActiveModel #:nodoc:
+module ActiveModel
 
   # == Active Model Validator
   #
@@ -26,7 +26,7 @@ module ActiveModel #:nodoc:
   #   end
   #
   # Any class that inherits from ActiveModel::Validator must implement a method
-  # called <tt>validate</tt> which accepts a <tt>record</tt>.
+  # called +validate+ which accepts a +record+.
   #
   #   class Person
   #     include ActiveModel::Validations
@@ -40,8 +40,8 @@ module ActiveModel #:nodoc:
   #     end
   #   end
   #
-  # To cause a validation error, you must add to the <tt>record</tt>'s errors directly
-  # from within the validators message
+  # To cause a validation error, you must add to the +record+'s errors directly
+  # from within the validators message.
   #
   #   class MyValidator < ActiveModel::Validator
   #     def validate(record)
@@ -61,7 +61,7 @@ module ActiveModel #:nodoc:
   #   end
   #
   # The easiest way to add custom validators for validating individual attributes
-  # is with the convenient <tt>ActiveModel::EachValidator</tt>. For example:
+  # is with the convenient <tt>ActiveModel::EachValidator</tt>.
   #
   #   class TitleValidator < ActiveModel::EachValidator
   #     def validate_each(record, attribute, value)
@@ -70,7 +70,7 @@ module ActiveModel #:nodoc:
   #   end
   #
   # This can now be used in combination with the +validates+ method
-  # (see <tt>ActiveModel::Validations::ClassMethods.validates</tt> for more on this)
+  # (see <tt>ActiveModel::Validations::ClassMethods.validates</tt> for more on this).
   #
   #   class Person
   #     include ActiveModel::Validations
@@ -81,8 +81,7 @@ module ActiveModel #:nodoc:
   #
   # Validator may also define a +setup+ instance method which will get called
   # with the class that using that validator as its argument. This can be
-  # useful when there are prerequisites such as an +attr_accessor+ being present
-  # for example:
+  # useful when there are prerequisites such as an +attr_accessor+ being present.
   #
   #   class MyValidator < ActiveModel::Validator
   #     def setup(klass)
@@ -92,15 +91,13 @@ module ActiveModel #:nodoc:
   #
   # This setup method is only called when used with validation macros or the
   # class level <tt>validates_with</tt> method.
-  #
   class Validator
     attr_reader :options
 
-    # Returns the kind of the validator. Examples:
+    # Returns the kind of the validator.
     #
     #   PresenceValidator.kind   # => :presence
     #   UniquenessValidator.kind # => :uniqueness
-    #
     def self.kind
       @kind ||= name.split('::').last.underscore.sub(/_validator$/, '').to_sym unless anonymous?
     end
@@ -111,6 +108,9 @@ module ActiveModel #:nodoc:
     end
 
     # Return the kind for this validator.
+    #
+    #   PresenceValidator.new.kind   # => :presence
+    #   UniquenessValidator.new.kind # => :uniqueness 
     def kind
       self.class.kind
     end
author	Vijay Dev <vijaydev.cse@gmail.com>	2012-08-04 15:18:35 +0530
committer	Vijay Dev <vijaydev.cse@gmail.com>	2012-08-04 15:18:35 +0530
commit	3d3fa165e40c8cdaaebdab9dd2985d0ca3a36236 (patch)
tree	21ae9b984d34c9487628097f3933f8fa14a3558f /activemodel
parent	c963f883a41913624363bfd8203b5640318198c2 (diff)
parent	b51201242aaf77c6db5a9b2f72e433c521df79c5 (diff)
download	rails-3d3fa165e40c8cdaaebdab9dd2985d0ca3a36236.tar.gz rails-3d3fa165e40c8cdaaebdab9dd2985d0ca3a36236.tar.bz2 rails-3d3fa165e40c8cdaaebdab9dd2985d0ca3a36236.zip