9 files changed, 24 insertions, 25 deletions
diff --git a/activemodel/lib/active_model/attribute_methods.rb b/activemodel/lib/active_model/attribute_methods.rb
index 391442afa7..2da2e8ec64 100644
--- a/activemodel/lib/active_model/attribute_methods.rb
+++ b/activemodel/lib/active_model/attribute_methods.rb
@@ -14,11 +14,11 @@ module ActiveModel
   class MissingAttributeError < NoMethodError
   end
 
-  # == Active Model Attribute Methods
+  # == Active \Model \Attribute \Methods
   #
-  # <tt>ActiveModel::AttributeMethods</tt> provides a way to add prefixes and
-  # suffixes to your methods as well as handling the creation of
-  # <tt>ActiveRecord::Base</tt>-like class methods such as +table_name+.
+  # Provides a way to add prefixes and suffixes to your methods as
+  # well as handling the creation of <tt>ActiveRecord::Base</tt>-like
+  # class methods such as +table_name+.
   #
   # The requirements to implement <tt>ActiveModel::AttributeMethods</tt> are to:
   #
@@ -27,7 +27,9 @@ module ActiveModel
   #   or +attribute_method_prefix+.
   # * Call +define_attribute_methods+ after the other methods are called.
   # * Define the various generic +_attribute+ methods that you have declared.
-  # * Define an +attributes+ method, see below.
+  # * Define an +attributes+ method which returns a hash with each
+  #   attribute name in your model as hash key and the attribute value as hash value.
+  #   Hash keys must be strings.
   #
   # A minimal implementation could be:
   #
@@ -42,7 +44,7 @@ module ActiveModel
   #     attr_accessor :name
   #
   #     def attributes
-  #       {'name' => @name}
+  #       { 'name' => @name }
   #     end
   #
   #     private
@@ -59,13 +61,6 @@ module ActiveModel
   #       send("#{attr}=", 'Default Name')
   #     end
   #   end
-  #
-  # Note that whenever you include <tt>ActiveModel::AttributeMethods</tt> in
-  # your class, it requires you to implement an +attributes+ method which
-  # returns a hash with each attribute name in your model as hash key and the
-  # attribute value as hash value.
-  #
-  # Hash keys must be strings.
   module AttributeMethods
     extend ActiveSupport::Concern
 
@@ -173,14 +168,14 @@ module ActiveModel
       #     private
       #
       #     def reset_attribute_to_default!(attr)
-      #       ...
+      #       send("#{attr}=", 'Default Name')
       #     end
       #   end
       #
       #   person = Person.new
       #   person.name                         # => 'Gem'
       #   person.reset_name_to_default!
-      #   person.name                         # => 'Gemma'
+      #   person.name                         # => 'Default Name'
       def attribute_method_affix(*affixes)
         self.attribute_method_matchers += affixes.map! { |affix| AttributeMethodMatcher.new prefix: affix[:prefix], suffix: affix[:suffix] }
         undefine_attribute_methods
@@ -250,7 +245,7 @@ module ActiveModel
       #     private
       #
       #     def clear_attribute(attr)
-      #       ...
+      #       send("#{attr}", nil)
       #     end
       #   end
       def define_attribute_methods(*attr_names)
diff --git a/activemodel/lib/active_model/callbacks.rb b/activemodel/lib/active_model/callbacks.rb
index 377aa6ee27..b27a39b787 100644
--- a/activemodel/lib/active_model/callbacks.rb
+++ b/activemodel/lib/active_model/callbacks.rb
@@ -30,7 +30,7 @@ module ActiveModel
   #   end
   #
   # Then in your class, you can use the +before_create+, +after_create+ and
-  # +around_create+ methods, just as you would in an Active Record module.
+  # +around_create+ methods, just as you would in an Active Record model.
   #
   #   before_create :action_before_create
   #
diff --git a/activemodel/lib/active_model/conversion.rb b/activemodel/lib/active_model/conversion.rb
index 1856c852a2..6b0a752566 100644
--- a/activemodel/lib/active_model/conversion.rb
+++ b/activemodel/lib/active_model/conversion.rb
@@ -1,5 +1,5 @@
 module ActiveModel
-  # == Active \Model Conversion
+  # == Active \Model \Conversion
   #
   # Handles default conversions: to_model, to_key, to_param, and to_partial_path.
   #
diff --git a/activemodel/lib/active_model/dirty.rb b/activemodel/lib/active_model/dirty.rb
index 8ccb25c613..58d87e6f7f 100644
--- a/activemodel/lib/active_model/dirty.rb
+++ b/activemodel/lib/active_model/dirty.rb
@@ -54,6 +54,7 @@ module ActiveModel
   #   person.name = 'Bob'
   #   person.changed?       # => true
   #   person.name_changed?  # => true
+  #   person.name_changed?(from: "Uncle Bob", to: "Bob") # => true
   #   person.name_was       # => "Uncle Bob"
   #   person.name_change    # => ["Uncle Bob", "Bob"]
   #   person.name = 'Bill'
@@ -149,8 +150,11 @@ module ActiveModel
     end
 
     # Handle <tt>*_changed?</tt> for +method_missing+.
-    def attribute_changed?(attr) # :nodoc:
-      changed_attributes.include?(attr)
+    def attribute_changed?(attr, options = {}) #:nodoc:
+      result = changed_attributes.include?(attr)
+      result &&= options[:to] == __send__(attr) if options.key?(:to)
+      result &&= options[:from] == changed_attributes[attr] if options.key?(:from)
+      result
     end
 
     # Handle <tt>*_was</tt> for +method_missing+.
diff --git a/activemodel/lib/active_model/model.rb b/activemodel/lib/active_model/model.rb
index f048dda5c6..63716eebb1 100644
--- a/activemodel/lib/active_model/model.rb
+++ b/activemodel/lib/active_model/model.rb
@@ -1,6 +1,6 @@
 module ActiveModel
 
-  # == Active \Model Basic \Model
+  # == Active \Model \Basic \Model
   #
   # Includes the required interface for an object to interact with
   # <tt>ActionPack</tt>, using different <tt>ActiveModel</tt> modules.
diff --git a/activemodel/lib/active_model/serializers/json.rb b/activemodel/lib/active_model/serializers/json.rb
index 05e2e089e5..c58e73f6a7 100644
--- a/activemodel/lib/active_model/serializers/json.rb
+++ b/activemodel/lib/active_model/serializers/json.rb
@@ -2,7 +2,7 @@ require 'active_support/json'
 
 module ActiveModel
   module Serializers
-    # == Active Model JSON Serializer
+    # == Active \Model \JSON \Serializer
     module JSON
       extend ActiveSupport::Concern
       include ActiveModel::Serialization
diff --git a/activemodel/lib/active_model/validations.rb b/activemodel/lib/active_model/validations.rb
index 31c2245265..6be44b5d63 100644
--- a/activemodel/lib/active_model/validations.rb
+++ b/activemodel/lib/active_model/validations.rb
@@ -4,7 +4,7 @@ require 'active_support/core_ext/hash/except'
 
 module ActiveModel
 
-  # == Active \Model Validations
+  # == Active \Model \Validations
   #
   # Provides a full validation framework to your objects.
   #
diff --git a/activemodel/lib/active_model/validations/callbacks.rb b/activemodel/lib/active_model/validations/callbacks.rb
index fde53b9f89..edfffdd3ce 100644
--- a/activemodel/lib/active_model/validations/callbacks.rb
+++ b/activemodel/lib/active_model/validations/callbacks.rb
@@ -1,6 +1,6 @@
 module ActiveModel
   module Validations
-    # == Active \Model Validation Callbacks
+    # == Active \Model \Validation \Callbacks
     #
     # Provides an interface for any class to have +before_validation+ and
     # +after_validation+ callbacks.
diff --git a/activemodel/lib/active_model/validations/length.rb b/activemodel/lib/active_model/validations/length.rb
index ddfd8a342e..a96b30cadd 100644
--- a/activemodel/lib/active_model/validations/length.rb
+++ b/activemodel/lib/active_model/validations/length.rb
@@ -1,6 +1,6 @@
 module ActiveModel
 
-  # == Active \Model Length \Validator
+  # == Active \Model Length Validator
   module Validations
     class LengthValidator < EachValidator # :nodoc:
       MESSAGES  = { is: :wrong_length, minimum: :too_short, maximum: :too_long }.freeze