[ci skip] Clarify deletion strategies for collection proxies

For detailed testing of behavior see:
https://gist.github.com/eileencodes/5b0a2fe011dcff6203fe

This shows destroy_all always destroys records and fires callbacks.
It will never use nullify or delete_all

delete_all's behavior varies greatly based on `hm` vs `hm:t` and deletion
strategy.

1 files changed, 14 insertions, 17 deletions

diff --git a/activerecord/lib/active_record/associations/collection_proxy.rb b/activerecord/lib/active_record/associations/collection_proxy.rb
index 8c7b0b4be9..060b2278d9 100644
--- a/activerecord/lib/active_record/associations/collection_proxy.rb
+++ b/activerecord/lib/active_record/associations/collection_proxy.rb
@@ -355,14 +355,15 @@ module ActiveRecord
         @association.replace(other_array)
       end
 
-      # Deletes all the records from the collection. For +has_many+ associations,
-      # the deletion is done according to the strategy specified by the <tt>:dependent</tt>
-      # option.
+      # Deletes all the records from the collection according to the strategy
+      # specified by the +:dependent+ option. If no +:dependent+ option is given,
+      # then it will follow the default strategy.
       #
-      # If no <tt>:dependent</tt> option is given, then it will follow the
-      # default strategy. The default strategy is <tt>:nullify</tt>. This
-      # sets the foreign keys to <tt>NULL</tt>. For, +has_many+ <tt>:through</tt>,
-      # the default strategy is +delete_all+.
+      # For +has_many :through+ associations, the default deletion strategy is
+      # +:delete_all+.
+      #
+      # For +has_many+ associations, the default deletion strategy is +:nullify+.
+      # This sets the foreign keys to +NULL+.
       #
       #   class Person < ActiveRecord::Base
       #     has_many :pets # dependent: :nullify option by default
@@ -393,9 +394,9 @@ module ActiveRecord
       #   #       #<Pet id: 3, name: "Choo-Choo", person_id: nil>
       #   #    ]
       #
-      # If it is set to <tt>:destroy</tt> all the objects from the collection
-      # are removed by calling their +destroy+ method. See +destroy+ for more
-      # information.
+      # Both +has_many+ and +has_many :through+ dependencies default to the
+      # +:delete_all+ strategy if the +:dependent+ option is set to +:destroy+.
+      # Records are not instantiated and callbacks will not be fired.
       #
       #   class Person < ActiveRecord::Base
       #     has_many :pets, dependent: :destroy
@@ -410,11 +411,6 @@ module ActiveRecord
       #   #    ]
       #
       #   person.pets.delete_all
-      #   # => [
-      #   #       #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>,
-      #   #       #<Pet id: 2, name: "Spook", person_id: 1>,
-      #   #       #<Pet id: 3, name: "Choo-Choo", person_id: 1>
-      #   #    ]
       #
       #   Pet.find(1, 2, 3)
       #   # => ActiveRecord::RecordNotFound
@@ -443,8 +439,9 @@ module ActiveRecord
       end
 
       # Deletes the records of the collection directly from the database
-      # ignoring the +:dependent+ option. It invokes +before_remove+,
-      # +after_remove+ , +before_destroy+ and +after_destroy+ callbacks.
+      # ignoring the +:dependent+ option. Records are instantiated and it
+      # invokes +before_remove+, +after_remove+ , +before_destroy+ and
+      # +after_destroy+ callbacks.
       #
       #   class Person < ActiveRecord::Base
       #     has_many :pets