Ticket #7377: callbacks_doc.diff

activerecord/lib/active_record/callbacks.rb

@@ -5 +5 @@
-  # before or after an alteration of the object state. This can be used to make sure that associated and
-  # dependent objects are deleted when destroy is called (by overwriting before_destroy) or to massage attributes
-  # before they're validated (by overwriting before_validation). As an example of the callbacks initiated, consider
-
+ on a new record
-  #
-  # * (-) save
-  # * (-) valid?
@@ -21 +21 @@
-  # * (7) after_create
-  # * (8) after_save
-  #
+  # and the Base#save call on an existing record:
+  #
+  # * (-) save
+  # * (-) valid?
+  # * (1) before_validation
+  # * (2) before_validation_on_update
+  # * (-) validate
+  # * (-) validate_on_update
+  # * (3) after_validation
+  # * (4) after_validation_on_update
+  # * (5) before_save
+  # * (6) before_update
+  # * (-) update
+  # * (7) after_update
+  # * (8) after_save
+  #
-  # That's a total of eight callbacks, which gives you immense power to react and prepare for each state in the
-  # Active Record lifecycle.
-  #
+  # Note: The destroy method has two callbacks
+  # * (-) destroy
+  # * (1) before_destroy
+  # * (-) delete operation
+  # * (2) after_destroy
+  #
-  # Examples:
-  #   class CreditCard < ActiveRecord::Base
-  #     # Strip everything but digits, so the user can specify "555 234 34" or
@@ -169 +191 @@
-  # If a before_* callback returns false, all the later callbacks and the associated action are cancelled. If an after_* callback returns
-  # false, all the later callbacks are cancelled. Callbacks are generally run in the order they are defined, with the exception of callbacks
-  # defined as methods on the model, which are called last.
+  #
-  module Callbacks
-    CALLBACKS = %w(
-      after_find after_initialize before_save after_save before_create after_create before_update after_update before_validation
@@ -228 +251 @@
-      result
-    end
-
-
+
+
+
-    def before_save() end
-
-Base.save
+a record is saved
-    #
+    # (See Callbacks for the order in which callbacks are executed)
+    #
-    #  class Contact < ActiveRecord::Base
-    #    after_save { logger.info( 'New contact saved!' ) }
-    #  end
@@ -244 +271 @@
-      result
-    end
-
-
+
+
+
-    def before_create() end
-
-
+
+
+
-    def after_create() end
-    def create_with_callbacks #:nodoc:
-      return false if callback(:before_create) == false
@@ -256 +287 @@
-      result
-    end
-
-
+
+
+
-    def before_update() end
-
-
+
+
+
-    def after_update() end
-
-    def update_with_callbacks #:nodoc:
@@ -270 +305 @@
-    end
-
-    # Is called _before_ Validations.validate (which is part of the Base.save call).
+    #
+    # (See Callbacks for the order in which callbacks are executed)    
-    def before_validation() end
-
-    # Is called _after_ Validations.validate (which is part of the Base.save call).
+    #
+    # (See Callbacks for the order in which callbacks are executed)
-    def after_validation() end
-
-    # Is called _before_ Validations.validate (which is part of the Base.save call) on new objects
-    # that haven't been saved yet (no record exists).
+    #
+    # (See Callbacks for the order in which callbacks are executed)
-    def before_validation_on_create() end
-
-    # Is called _after_ Validations.validate (which is part of the Base.save call) on new objects
-    # that haven't been saved yet (no record exists).
+    #
+    # (See Callbacks for the order in which callbacks are executed)
-    def after_validation_on_create()  end
-
-    # Is called _before_ Validations.validate (which is part of the Base.save call) on
-    # existing objects that have a record.
+    #
+    # (See Callbacks for the order in which callbacks are executed)
-    def before_validation_on_update() end
-
-    # Is called _after_ Validations.validate (which is part of the Base.save call) on
-    # existing objects that have a record.
+    #
+    # (See Callbacks for the order in which callbacks are executed)
-    def after_validation_on_update()  end
-
-    def valid_with_callbacks? #:nodoc:
@@ -308 +355 @@
-    #
-    # Note: If you need to _destroy_ or _nullify_ associated records first,
-    # use the _:dependent_ option on your associations.
+    # Note that before_ and after_ validations are not run (i.e. there is no new info to validate)
+    #
+    # (See Callbacks for the order in which callbacks are executed)
-    def before_destroy() end
-
-    # Is called _after_ Base.destroy (and all the attributes have been frozen).
@@ -315 +365 @@
-    #  class Contact < ActiveRecord::Base
-    #    after_destroy { |record| logger.info( "Contact #{record.id} was destroyed." ) }
-    #  end
+    #
+    # (See Callbacks for the order in which callbacks are executed)
-    def after_destroy()  end
-    def destroy_with_callbacks #:nodoc:
-      return false if callback(:before_destroy) == false