Clarify documentation on ActiveRecord Callbacks

olivierlacan · olivierlacan · commit a91e3c7f3b75 · 2020-02-24T10:26:34.000-05:00
Mainly these changes aim to make this documentation a bit more ESL (English as a second language friendly). Here are some examples of the things I changed: - replace the constant use of `get <verb>` with `is <verb>` - replace $10 words like `alteration` with clearer $1 words like `change` - `give you immense power` -> `offer you a lot of control` - missing `<code>` wrapping to denote method/variable references and SQL statements like `COMMIT` and `ROLLBACK`. - clarify the ordering callback example specifically to explain what children is (an association with records) This is minimal stuff but I think it improves the clarity and legibility of this extremely important piece of documentation. I'm actually surprised that it's not linked to from the [Callbacks Guide][1] [ci skip] [1]: https://guides.rubyonrails.org/active_record_callbacks.html
diff --git a/activerecord/lib/active_record/callbacks.rb b/activerecord/lib/active_record/callbacks.rb
@@ -4,7 +4,7 @@ module ActiveRecord
   # = Active Record \Callbacks
   #
   # \Callbacks are hooks into the life cycle of an Active Record object that allow you to trigger logic
-  # before or after an alteration of the object state. This can be used to make sure that associated and
+  # before or after a change in the object state. This can be used to make sure that associated and
   # dependent objects are deleted when {ActiveRecord::Base#destroy}[rdoc-ref:Persistence#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 the {ActiveRecord::Base#save}[rdoc-ref:Persistence#save] call for a new record:
@@ -21,8 +21,8 @@ module ActiveRecord
   # * (6) <tt>after_save</tt>
   # * (7) <tt>after_commit</tt>
   #
-  # Also, an <tt>after_rollback</tt> callback can be configured to be triggered whenever a rollback is issued.
   # Check out ActiveRecord::Transactions for more details about <tt>after_commit</tt> and
+  # Also, an <tt>after_rollback</tt> callback can be configured to be triggered whenever a rollback is issued.
   # <tt>after_rollback</tt>.
   #
   # Additionally, an <tt>after_touch</tt> callback is triggered whenever an
@@ -32,7 +32,7 @@ module ActiveRecord
   # is found and instantiated by a finder, with <tt>after_initialize</tt> being triggered after new objects
   # are instantiated as well.
   #
-  # There are nineteen callbacks in total, which give you immense power to react and prepare for each state in the
+  # There are nineteen callbacks in total, which give a lot of control over how to react and prepare for each state in the
   # Active Record life cycle. The sequence for calling {ActiveRecord::Base#save}[rdoc-ref:Persistence#save] for an existing record is similar,
   # except that each <tt>_create</tt> callback is replaced by the corresponding <tt>_update</tt> callback.
   #
@@ -64,7 +64,7 @@ module ActiveRecord
   #
   # Besides the overwritable callback methods, it's also possible to register callbacks through the
   # use of the callback macros. Their main advantage is that the macros add behavior into a callback
-  # queue that is kept intact down through an inheritance hierarchy.
+  # queue that is kept intact through an inheritance hierarchy.
   #
   #   class Topic < ActiveRecord::Base
   #     before_destroy :destroy_author
@@ -74,7 +74,7 @@ module ActiveRecord
   #     before_destroy :destroy_readers
   #   end
   #
-  # Now, when <tt>Topic#destroy</tt> is run only +destroy_author+ is called. When <tt>Reply#destroy</tt> is
+  # When <tt>Topic#destroy</tt> is run only +destroy_author+ is called. When <tt>Reply#destroy</tt> is
   # run, both +destroy_author+ and +destroy_readers+ are called.
   #
   # *IMPORTANT:* In order for inheritance to work for the callback queues, you must specify the
@@ -83,10 +83,9 @@ module ActiveRecord
   #
   # == Types of callbacks
   #
-  # There are three types of callbacks accepted by the callback macros: Method references (symbol), callback objects,
-  # and inline methods (using a proc). Method references and callback objects
-  # are the recommended approaches, inline methods using a proc are sometimes appropriate (such as for
-  # creating mix-ins).
+  # There are four types of callbacks accepted by the callback macros: method references (symbol), callback objects,
+  # inline methods (using a proc). Method references and callback objects are the recommended approaches,
+  # inline methods using a proc are sometimes appropriate (such as for creating mix-ins).
   #
   # The method reference callbacks work by specifying a protected or private method available in the object, like this:
   #
@@ -179,8 +178,8 @@ module ActiveRecord
   #
   # == Ordering callbacks
   #
-  # Sometimes the code needs that the callbacks execute in a specific order. For example, a +before_destroy+
-  # callback (+log_children+ in this case) should be executed before the children get destroyed by the
+  # Sometimes application code requires that callbacks execute in a specific order. For example, a +before_destroy+
+  # callback (+log_children+ in this case) should be executed before records in the +children+ association are destroyed by the
   # <tt>dependent: :destroy</tt> option.
   #
   # Let's look at the code below:
@@ -196,8 +195,8 @@ module ActiveRecord
   #       end
   #   end
   #
-  # In this case, the problem is that when the +before_destroy+ callback is executed, the children are not available
-  # because the {ActiveRecord::Base#destroy}[rdoc-ref:Persistence#destroy] callback gets executed first.
+  # In this case, the problem is that when the +before_destroy+ callback is executed, records in the +children+ association no
+  # longer exist because the {ActiveRecord::Base#destroy}[rdoc-ref:Persistence#destroy] callback was executed first.
   # You can use the +prepend+ option on the +before_destroy+ callback to avoid this.
   #
   #   class Topic < ActiveRecord::Base
@@ -211,7 +210,7 @@ module ActiveRecord
   #       end
   #   end
   #
-  # This way, the +before_destroy+ gets executed before the <tt>dependent: :destroy</tt> is called, and the data is still available.
+  # This way, the +before_destroy+ is 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.
@@ -235,10 +234,10 @@ module ActiveRecord
   #     end
   #   end
   #
-  # In this case the +log_children+ gets executed before +do_something_else+.
+  # In this case the +log_children+ is 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
+  # As seen below, in case there are multiple transactional callbacks the order
   # is reversed.
   #
   # For example:
@@ -260,16 +259,16 @@ module ActiveRecord
   #     end
   #   end
   #
-  # In this case the +do_something_else+ gets executed before +log_children+.
+  # In this case the +do_something_else+ is executed before +log_children+.
   #
   # == \Transactions
   #
   # The entire callback chain of a {#save}[rdoc-ref:Persistence#save], {#save!}[rdoc-ref:Persistence#save!],
   # or {#destroy}[rdoc-ref:Persistence#destroy] call runs within a transaction. That includes <tt>after_*</tt> hooks.
-  # If everything goes fine a COMMIT is executed once the chain has been completed.
+  # If everything goes fine a +COMMIT+ is executed once the chain has been completed.
   #
-  # If a <tt>before_*</tt> callback cancels the action a ROLLBACK is issued. You
-  # can also trigger a ROLLBACK raising an exception in any of the callbacks,
+  # If a <tt>before_*</tt> callback cancels the action a +ROLLBACK+ is issued. You
+  # can also trigger a +ROLLBACK+ raising an exception in any of the callbacks,
   # including <tt>after_*</tt> hooks. Note, however, that in that case the client
   # needs to be aware of it because an ordinary {#save}[rdoc-ref:Persistence#save] will raise such exception
   # instead of quietly returning +false+.
@@ -280,17 +279,17 @@ module ActiveRecord
   # <tt>:before</tt>, <tt>:after</tt> and <tt>:around</tt> as values for the <tt>kind</tt> property. The <tt>kind</tt> property
   # defines what part of the chain the callback runs in.
   #
-  # To find all callbacks in the before_save callback chain:
+  # To find all callbacks in the +before_save+ callback chain:
   #
   #   Topic._save_callbacks.select { |cb| cb.kind.eql?(:before) }
   #
-  # Returns an array of callback objects that form the before_save chain.
+  # Returns an array of callback objects that form the +before_save+ chain.
   #
   # To further check if the before_save chain contains a proc defined as <tt>rest_when_dead</tt> use the <tt>filter</tt> property of the callback object:
   #
   #   Topic._save_callbacks.select { |cb| cb.kind.eql?(:before) }.collect(&:filter).include?(:rest_when_dead)
   #
-  # Returns true or false depending on whether the proc is contained in the before_save callback chain on a Topic model.
+  # Returns true or false depending on whether the proc is contained in the +before_save+ callback chain on a Topic model.
   #
   module Callbacks
     extend ActiveSupport::Concern

Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,7 @@ module ActiveRecord`
`4`	`4`	`# = Active Record \Callbacks`
`5`	`5`	`#`
`6`	`6`	`# \Callbacks are hooks into the life cycle of an Active Record object that allow you to trigger logic`
`7`		`- # before or after an alteration of the object state. This can be used to make sure that associated and`
	`7`	`+ # before or after a change in the object state. This can be used to make sure that associated and`
`8`	`8`	`# dependent objects are deleted when {ActiveRecord::Base#destroy}[rdoc-ref:Persistence#destroy] is called (by overwriting +before_destroy+) or`
`9`	`9`	`# to massage attributes before they're validated (by overwriting +before_validation+).`
`10`	`10`	`# As an example of the callbacks initiated, consider the {ActiveRecord::Base#save}[rdoc-ref:Persistence#save] call for a new record:`
`@@ -21,8 +21,8 @@ module ActiveRecord`
`21`	`21`	`# * (6) <tt>after_save</tt>`
`22`	`22`	`# * (7) <tt>after_commit</tt>`
`23`	`23`	`#`
`24`		`- # Also, an <tt>after_rollback</tt> callback can be configured to be triggered whenever a rollback is issued.`
`25`	`24`	`# Check out ActiveRecord::Transactions for more details about <tt>after_commit</tt> and`
	`25`	`+ # Also, an <tt>after_rollback</tt> callback can be configured to be triggered whenever a rollback is issued.`
`26`	`26`	`# <tt>after_rollback</tt>.`
`27`	`27`	`#`
`28`	`28`	`# Additionally, an <tt>after_touch</tt> callback is triggered whenever an`
`@@ -32,7 +32,7 @@ module ActiveRecord`
`32`	`32`	`# is found and instantiated by a finder, with <tt>after_initialize</tt> being triggered after new objects`
`33`	`33`	`# are instantiated as well.`
`34`	`34`	`#`
`35`		`- # There are nineteen callbacks in total, which give you immense power to react and prepare for each state in the`
	`35`	`+ # There are nineteen callbacks in total, which give a lot of control over how to react and prepare for each state in the`
`36`	`36`	`# Active Record life cycle. The sequence for calling {ActiveRecord::Base#save}[rdoc-ref:Persistence#save] for an existing record is similar,`
`37`	`37`	`# except that each <tt>_create</tt> callback is replaced by the corresponding <tt>_update</tt> callback.`
`38`	`38`	`#`
`@@ -64,7 +64,7 @@ module ActiveRecord`
`64`	`64`	`#`
`65`	`65`	`# Besides the overwritable callback methods, it's also possible to register callbacks through the`
`66`	`66`	`# use of the callback macros. Their main advantage is that the macros add behavior into a callback`
`67`		`- # queue that is kept intact down through an inheritance hierarchy.`
	`67`	`+ # queue that is kept intact through an inheritance hierarchy.`
`68`	`68`	`#`
`69`	`69`	`# class Topic < ActiveRecord::Base`
`70`	`70`	`# before_destroy :destroy_author`
`@@ -74,7 +74,7 @@ module ActiveRecord`
`74`	`74`	`# before_destroy :destroy_readers`
`75`	`75`	`# end`
`76`	`76`	`#`
`77`		`- # Now, when <tt>Topic#destroy</tt> is run only +destroy_author+ is called. When <tt>Reply#destroy</tt> is`
	`77`	`+ # When <tt>Topic#destroy</tt> is run only +destroy_author+ is called. When <tt>Reply#destroy</tt> is`
`78`	`78`	`# run, both +destroy_author+ and +destroy_readers+ are called.`
`79`	`79`	`#`
`80`	`80`	`# IMPORTANT: In order for inheritance to work for the callback queues, you must specify the`
`@@ -83,10 +83,9 @@ module ActiveRecord`
`83`	`83`	`#`
`84`	`84`	`# == Types of callbacks`
`85`	`85`	`#`
`86`		`- # There are three types of callbacks accepted by the callback macros: Method references (symbol), callback objects,`
`87`		`- # and inline methods (using a proc). Method references and callback objects`
`88`		`- # are the recommended approaches, inline methods using a proc are sometimes appropriate (such as for`
`89`		`- # creating mix-ins).`
	`86`	`+ # There are four types of callbacks accepted by the callback macros: method references (symbol), callback objects,`
	`87`	`+ # inline methods (using a proc). Method references and callback objects are the recommended approaches,`
	`88`	`+ # inline methods using a proc are sometimes appropriate (such as for creating mix-ins).`
`90`	`89`	`#`
`91`	`90`	`# The method reference callbacks work by specifying a protected or private method available in the object, like this:`
`92`	`91`	`#`
`@@ -179,8 +178,8 @@ module ActiveRecord`
`179`	`178`	`#`
`180`	`179`	`# == Ordering callbacks`
`181`	`180`	`#`
`182`		`- # Sometimes the code needs that the callbacks execute in a specific order. For example, a +before_destroy+`
`183`		`- # callback (+log_children+ in this case) should be executed before the children get destroyed by the`
	`181`	`+ # Sometimes application code requires that callbacks execute in a specific order. For example, a +before_destroy+`
	`182`	`+ # callback (+log_children+ in this case) should be executed before records in the +children+ association are destroyed by the`
`184`	`183`	`# <tt>dependent: :destroy</tt> option.`
`185`	`184`	`#`
`186`	`185`	`# Let's look at the code below:`
`@@ -196,8 +195,8 @@ module ActiveRecord`
`196`	`195`	`# end`
`197`	`196`	`# end`
`198`	`197`	`#`
`199`		`- # In this case, the problem is that when the +before_destroy+ callback is executed, the children are not available`
`200`		`- # because the {ActiveRecord::Base#destroy}[rdoc-ref:Persistence#destroy] callback gets executed first.`
	`198`	`+ # In this case, the problem is that when the +before_destroy+ callback is executed, records in the +children+ association no`
	`199`	`+ # longer exist because the {ActiveRecord::Base#destroy}[rdoc-ref:Persistence#destroy] callback was executed first.`
`201`	`200`	`# You can use the +prepend+ option on the +before_destroy+ callback to avoid this.`
`202`	`201`	`#`
`203`	`202`	`# class Topic < ActiveRecord::Base`
`@@ -211,7 +210,7 @@ module ActiveRecord`
`211`	`210`	`# end`
`212`	`211`	`# end`
`213`	`212`	`#`
`214`		`- # This way, the +before_destroy+ gets executed before the <tt>dependent: :destroy</tt> is called, and the data is still available.`
	`213`	`+ # This way, the +before_destroy+ is executed before the <tt>dependent: :destroy</tt> is called, and the data is still available.`
`215`	`214`	`#`
`216`	`215`	`# Also, there are cases when you want several callbacks of the same type to`
`217`	`216`	`# be executed in order.`
`@@ -235,10 +234,10 @@ module ActiveRecord`
`235`	`234`	`# end`
`236`	`235`	`# end`
`237`	`236`	`#`
`238`		`- # In this case the +log_children+ gets executed before +do_something_else+.`
	`237`	`+ # In this case the +log_children+ is executed before +do_something_else+.`
`239`	`238`	`# The same applies to all non-transactional callbacks.`
`240`	`239`	`#`
`241`		`- # In case there are multiple transactional callbacks as seen below, the order`
	`240`	`+ # As seen below, in case there are multiple transactional callbacks the order`
`242`	`241`	`# is reversed.`
`243`	`242`	`#`
`244`	`243`	`# For example:`
`@@ -260,16 +259,16 @@ module ActiveRecord`
`260`	`259`	`# end`
`261`	`260`	`# end`
`262`	`261`	`#`
`263`		`- # In this case the +do_something_else+ gets executed before +log_children+.`
	`262`	`+ # In this case the +do_something_else+ is executed before +log_children+.`
`264`	`263`	`#`
`265`	`264`	`# == \Transactions`
`266`	`265`	`#`
`267`	`266`	`# The entire callback chain of a {#save}[rdoc-ref:Persistence#save], {#save!}[rdoc-ref:Persistence#save!],`
`268`	`267`	`# or {#destroy}[rdoc-ref:Persistence#destroy] call runs within a transaction. That includes <tt>after_*</tt> hooks.`
`269`		`- # If everything goes fine a COMMIT is executed once the chain has been completed.`
	`268`	`+ # If everything goes fine a +COMMIT+ is executed once the chain has been completed.`
`270`	`269`	`#`
`271`		`- # If a <tt>before_*</tt> callback cancels the action a ROLLBACK is issued. You`
`272`		`- # can also trigger a ROLLBACK raising an exception in any of the callbacks,`
	`270`	`+ # If a <tt>before_*</tt> callback cancels the action a +ROLLBACK+ is issued. You`
	`271`	`+ # can also trigger a +ROLLBACK+ raising an exception in any of the callbacks,`
`273`	`272`	`# including <tt>after_*</tt> hooks. Note, however, that in that case the client`
`274`	`273`	`# needs to be aware of it because an ordinary {#save}[rdoc-ref:Persistence#save] will raise such exception`
`275`	`274`	`# instead of quietly returning +false+.`
`@@ -280,17 +279,17 @@ module ActiveRecord`
`280`	`279`	`# <tt>:before</tt>, <tt>:after</tt> and <tt>:around</tt> as values for the <tt>kind</tt> property. The <tt>kind</tt> property`
`281`	`280`	`# defines what part of the chain the callback runs in.`
`282`	`281`	`#`
`283`		`- # To find all callbacks in the before_save callback chain:`
	`282`	`+ # To find all callbacks in the +before_save+ callback chain:`
`284`	`283`	`#`
`285`	`284`	`# Topic._save_callbacks.select { \|cb\| cb.kind.eql?(:before) }`
`286`	`285`	`#`
`287`		`- # Returns an array of callback objects that form the before_save chain.`
	`286`	`+ # Returns an array of callback objects that form the +before_save+ chain.`
`288`	`287`	`#`
`289`	`288`	`# To further check if the before_save chain contains a proc defined as <tt>rest_when_dead</tt> use the <tt>filter</tt> property of the callback object:`
`290`	`289`	`#`
`291`	`290`	`# Topic._save_callbacks.select { \|cb\| cb.kind.eql?(:before) }.collect(&:filter).include?(:rest_when_dead)`
`292`	`291`	`#`
`293`		`- # Returns true or false depending on whether the proc is contained in the before_save callback chain on a Topic model.`
	`292`	`+ # Returns true or false depending on whether the proc is contained in the +before_save+ callback chain on a Topic model.`
`294`	`293`	`#`
`295`	`294`	`module Callbacks`
`296`	`295`	`extend ActiveSupport::Concern`