Update callbacks documentation. Closes #3970.

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@4585 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

activerecord/CHANGELOG

@@ -1,5 +1,7 @@
 *SVN*
 
+* Update callbacks documentation. #3970 [Robby Russell <robby@planetargon.com>]
+
 * Don't modify options parameters in-place. #3819 [mpalmer@hezmatt.org]
 
 * PostgreSQL: correctly quote the ' in pk_and_sequence_for. #5462 [tietew@tietew.net]

activerecord/lib/active_record/callbacks.rb

@@ -232,6 +232,10 @@ module ActiveRecord
     def before_save() end
 
     # Is called _after_ Base.save (regardless of whether it's a create or update save).
+    #
+    #  class Contact < ActiveRecord::Base
+    #    after_save { logger.info( 'New contact saved!' ) }
+    #  end
     def after_save()  end
     def create_or_update_with_callbacks #:nodoc:
       return false if callback(:before_save) == false
@@ -301,9 +305,16 @@ module ActiveRecord
     end
 
     # Is called _before_ Base.destroy.
+    #
+    # Note: If you need to _destroy_ or _nullify_ associated records first,
+    # use the _:dependent_ option on your associations.
     def before_destroy() end
 
     # Is called _after_ Base.destroy (and all the attributes have been frozen).
+    #
+    #  class Contact < ActiveRecord::Base
+    #    after_destroy { |record| logger.info( "Contact #{record.id} was destroyed." ) }
+    #  end
     def after_destroy()  end
     def destroy_with_callbacks #:nodoc:
       return false if callback(:before_destroy) == false