Merge pull request #48616 from p8/activerecord/document-dirty

Document `ActiveRecord::Dirty` module in the API docs

activemodel/lib/active_model/dirty.rb

@@ -117,6 +117,9 @@ module ActiveModel
   #   person.name_change # => ["Bill", "Bill"]
   #   person.name << 'y'
   #   person.name_change # => ["Bill", "Billy"]
+  #
+  # Methods can be invoked as +name_changed?+ or by passing an argument to the
+  # generic method <tt>attribute_changed?("name")</tt>.
   module Dirty
     extend ActiveSupport::Concern
     include ActiveModel::AttributeMethods

activerecord/lib/active_record/attribute_methods/dirty.rb

@@ -5,6 +5,37 @@
 module ActiveRecord
   module AttributeMethods
     # = Active Record Attribute Methods \Dirty
+    #
+    # Provides a way to track changes in your Active Record models. It adds all
+    # methods from ActiveModel::Dirty and adds database specific methods.
+    #
+    # A newly created +Person+ object is unchanged:
+    #
+    #   class Person < ActiveRecord::Base
+    #   end
+    #
+    #   person = Person.create(name: "Alisson")
+    #   person.changed? # => false
+    #
+    # Change the name:
+    #
+    #   person.name = 'Alice'
+    #   person.name_in_database          # => "Allison"
+    #   person.will_save_change_to_name? # => true
+    #   person.name_change_to_be_saved   # => ["Allison", "Alice"]
+    #   person.changes_to_save           # => {"name"=>["Allison", "Alice"]}
+    #
+    # Save the changes:
+    #
+    #   person.save
+    #   person.name_in_database        # => "Alice"
+    #   person.saved_change_to_name?   # => true
+    #   person.saved_change_to_name    # => ["Allison", "Alice"]
+    #   person.name_before_last_change # => "Allison"
+    #
+    # Similar to ActiveModel::Dirty, methods can be invoked as
+    # +saved_change_to_name?+ or by passing an argument to the generic method
+    # <tt>saved_change_to_attribute?("name")</tt>.
     module Dirty
       extend ActiveSupport::Concern