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

Improve the guide about `has_many` `collection.clear` to indicate
the behavior for each dependent strategy according to
`collection.delete_all`.

Based on #17179, I changed the `collection.delete` docs to also
clarify the default strategy for each `hm` and `hm:t` associations.

Fixes #20170.

1 files changed, 7 insertions, 1 deletions

diff --git a/guides/source/association_basics.md b/guides/source/association_basics.md
index b9c9995a79..3f63c31cce 100644
--- a/guides/source/association_basics.md
+++ b/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?`