Merge pull request #42630 from nickborromeo/update-association-callback-docs

Update association callback docs [ci-skip]

activerecord/lib/active_record/associations.rb

@@ -594,19 +594,27 @@ module ActiveRecord
       # you can also define callbacks that get triggered when you add an object to or remove an
       # object from an association collection.
       #
-      #   class Project
-      #     has_and_belongs_to_many :developers, after_add: :evaluate_velocity
+      #   class Firm < ActiveRecord::Base
+      #     has_many :clients,
+      #              dependent: :destroy,
+      #              after_add: :congratulate_client,
+      #              after_remove: :log_after_remove
       #
-      #     def evaluate_velocity(developer)
-      #       ...
+      #     def congratulate_client(record)
+      #       # ...
+      #     end
+      #
+      #     def log_after_remove(record)
+      #       # ...
       #     end
-      #   end
       #
       # It's possible to stack callbacks by passing them as an array. Example:
       #
-      #   class Project
-      #     has_and_belongs_to_many :developers,
-      #                             after_add: [:evaluate_velocity, Proc.new { |p, d| p.shipping_date = Time.now}]
+      #   class Firm < ActiveRecord::Base
+      #     has_many :clients,
+      #              dependent: :destroy,
+      #              after_add: [:congratulate_client, -> (firm, record) { firm.log << "after_adding#{record.id}" }],
+      #              after_remove: :log_after_remove
       #   end
       #
       # Possible callbacks are: +before_add+, +after_add+, +before_remove+ and +after_remove+.
@@ -617,6 +625,18 @@ module ActiveRecord
       # Similarly, if any of the +before_remove+ callbacks throw an exception, the object
       # will not be removed from the collection.
       #
+      # Note: To trigger remove callbacks, you must use +destroy+ / +destroy_all+ methods. For example:
+      #
+      #   * <tt>firm.clients.destroy(client)</tt>
+      #   * <tt>firm.clients.destroy(*clients)</tt>
+      #   * <tt>firm.clients.destroy_all</tt>
+      #
+      # +delete+ / +delete_all+ methods like the following do *not* trigger remove callbacks:
+      #
+      #   * <tt>firm.clients.delete(client)</tt>
+      #   * <tt>firm.clients.delete(*clients)</tt>
+      #   * <tt>firm.clients.delete_all</tt>
+      #
       # == Association extensions
       #
       # The proxy objects that control the access to associations can be extended through anonymous