Merge pull request rails#27294 from eavgerinos/doc-ar-callbacks-order

[documentation] ActiveRecord: Document order of Callbacks

Author: rafaelfranca

activerecord/lib/active_record/callbacks.rb

@@ -225,6 +225,55 @@ module ActiveRecord
   #
   # This way, the +before_destroy+ gets executed before the <tt>dependent: :destroy</tt> is called, and the data is still available.
   #
+  # Also, there are cases when you want several callbacks of the same type to
+  # be executed in order.
+  #
+  # For example:
+  #
+  #   class Topic
+  #     has_many :children
+  #
+  #     after_save :log_children
+  #     after_save :do_something_else
+  #
+  #     private
+  #
+  #     def log_chidren
+  #       # Child processing
+  #     end
+  #
+  #     def do_something_else
+  #       # Something else
+  #     end
+  #   end
+  #
+  # In this case the +log_children+ gets executed before +do_something_else+.
+  # The same applies to all non-transactional callbacks.
+  #
+  # In case there are multiple transactional callbacks as seen below, the order
+  # is reversed.
+  #
+  # For example:
+  #
+  #   class Topic
+  #     has_many :children
+  #
+  #     after_commit :log_children
+  #     after_commit :do_something_else
+  #
+  #     private
+  #
+  #     def log_chidren
+  #       # Child processing
+  #     end
+  #
+  #     def do_something_else
+  #       # Something else
+  #     end
+  #   end
+  #
+  # In this case the +do_something_else+ gets executed before +log_children+.
+  #
   # == \Transactions
   #
   # The entire callback chain of a {#save}[rdoc-ref:Persistence#save], {#save!}[rdoc-ref:Persistence#save!],