Merge pull request #20421 from repinel/fix-clear-guides-and-related-api-docs

[ci skip] fix the `collection.clear` guide

activerecord/lib/active_record/associations/collection_proxy.rb

@@ -470,15 +470,16 @@ def destroy_all
         @association.destroy_all
       end
 
-      # Deletes the +records+ supplied and removes them from the collection. For
-      # +has_many+ associations, the deletion is done according to the strategy
-      # specified by the <tt>:dependent</tt> option. Returns an array with the
+      # Deletes the +records+ supplied 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. Returns an array with the
       # deleted records.
       #
-      # 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

guides/source/association_basics.md

@@ -1467,7 +1467,13 @@ The `collection_singular_ids=` method makes the collection contain only the obje
 
 ##### `collection.clear`
 
-The `collection.clear` method removes every object from the collection. This destroys the associated objects if they are associated with `dependent: :destroy`, deletes them directly from the database if `dependent: :delete_all`, and otherwise sets their foreign keys to `NULL`.
+The `collection.clear` method removes all objects from the collection according to the strategy specified by the `dependent` option. If no option is given, it follows the default strategy. The default strategy for `has_many :through` associations is `delete_all`, and for `has_many` associations is to set the foreign keys to `NULL`.
+
+```ruby
+@customer.orders.clear
+```
+
+WARNING: Objects will be delete if they're associated with `dependent: :destroy`, just like `dependent: :delete_all`.
 
 ##### `collection.empty?`