add CollectionProxy#delete documentation

activerecord/lib/active_record/associations/collection_proxy.rb

@@ -343,6 +343,9 @@ class CollectionProxy < Relation
       ##
       # :method: delete_all
       #
+      # :call-seq:
+      #   delete_all()
+      #
       # Deletes all the records from the collection. For +has_many+ asssociations,
       # the deletion is done according to the strategy specified by the <tt>:dependent</tt>
       # option. Returns an array with the deleted records.
@@ -435,6 +438,9 @@ class CollectionProxy < Relation
       ##
       # :method: destroy_all
       #
+      # :call-seq:
+      #   destroy_all()
+      #
       # Deletes the records of the collection directly from the database.
       # This will _always_ remove the records ignoring the +:dependent+
       # option.
@@ -458,13 +464,110 @@ class CollectionProxy < Relation
       #
       #   Pet.find(1) # => Couldn't find Pet with id=1
 
+      ##
+      # :method: delete
+      #
+      # :call-seq:
+      #   delete(*records)
+      #
+      # Deletes the +records+ supplied and remove 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
+      # 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+.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets # dependent: :nullify option by default
+      #   end
+      #
+      #   person.pets.size # => 3
+      #   person.pets
+      #   # => [
+      #   #       #<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>
+      #   #    ]
+      #
+      #   person.pets.delete(Pet.find(1))
+      #   # => [#<Pet id: 1, name: "Fancy-Fancy", person_id: 1>]
+      #
+      #   person.pets.size # => 2
+      #   person.pets
+      #   # => [
+      #   #       #<Pet id: 2, name: "Spook", person_id: 1>,
+      #   #       #<Pet id: 3, name: "Choo-Choo", person_id: 1>
+      #   #    ]
+      #
+      #   Pet.find(1)
+      #   # => #<Pet id: 1, name: "Fancy-Fancy", person_id: nil>
+      #
+      # If it is set to <tt>:destroy</tt> all the +records+ are removed by calling
+      # their +destroy+ method. See +destroy+ for more information.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets, dependent: :destroy
+      #   end
+      #
+      #   person.pets.size # => 3
+      #   person.pets
+      #   # => [
+      #   #       #<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>
+      #   #    ]
+      #
+      #   person.pets.delete([Pet.find(1), Pet.find(3)])
+      #   # => [
+      #   #       #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>,
+      #   #       #<Pet id: 3, name: "Choo-Choo", person_id: 1>
+      #   #    ]
+      #
+      #   person.pets.size # => 1
+      #   person.pets
+      #   # => [#<Pet id: 2, name: "Spook", person_id: 1>]
+      #
+      #   Pet.find(1, 3)
+      #   # => ActiveRecord::RecordNotFound: Couldn't find all Pets with IDs (1, 3)
+      #
+      # If it is set to <tt>:delete_all</tt>, all the +records+ are deleted
+      # *without* calling their +destroy+ method.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets, dependent: :delete_all
+      #   end
+      #
+      #   person.pets.size # => 3
+      #   person.pets
+      #   # => [
+      #   #       #<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>
+      #   #    ]
+      #
+      #   person.pets.delete(Pet.find(1))
+      #   # => [#<Pet id: 1, name: "Fancy-Fancy", person_id: 1>]
+      #
+      #   person.pets.size # => 2
+      #   person.pets
+      #   # => [
+      #   #       #<Pet id: 2, name: "Spook", person_id: 1>,
+      #   #       #<Pet id: 3, name: "Choo-Choo", person_id: 1>
+      #   #    ]
+      #
+      #   Pet.find(1)
+      #   # => ActiveRecord::RecordNotFound: Couldn't find Pet with id=1
+
       ##
       # :method: destroy
       #
       # :call-seq:
       #   destroy(*records)
       #
-      # Destroy the +records+ supplied and remove them from the collection.
+      # Destroys the +records+ supplied and remove them from the collection.
       # This method will _always_ remove record from the database ignoring
       # the +:dependent+ option. Returns an array with the removed records.
       #