improve CollectionProxy#destroy documentation

activerecord/lib/active_record/associations/collection_proxy.rb

@@ -248,7 +248,7 @@ class CollectionProxy < Relation
       # :method: destroy
       # Destroy 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 deleted records.
+      # the +:dependent+ option. Returns an array with the removed records.
       #
       #   class Person < ActiveRecord::Base
       #     has_many :pets
@@ -278,10 +278,42 @@ class CollectionProxy < Relation
       #   #       #<Pet id: 3, name: "Choo-Choo", person_id: 1>
       #   #    ]
       #
-      #   person.pets.size # => 0
-      #   person.pets      # => []
+      #   person.pets.size  # => 0
+      #   person.pets       # => []
       #
-      #   Pet.find([1, 2, 3]) # => ActiveRecord::RecordNotFound: Couldn't find all Pets with IDs (1, 2, 3)
+      #   Pet.find(1, 2, 3) # => ActiveRecord::RecordNotFound: Couldn't find all Pets with IDs (1, 2, 3)
+      #
+      # You can pass +Fixnum+ or +String+ values, it finds the records
+      # responding to the +id+ and then deletes them from the database.
+      #
+      #   person.pets.size # => 3  
+      #   person.pets
+      #   # => [
+      #   #       #<Pet id: 4, name: "Benny", person_id: 1>,
+      #   #       #<Pet id: 5, name: "Brain", person_id: 1>,
+      #   #       #<Pet id: 6, name: "Boss",  person_id: 1>
+      #   #    ]
+      #
+      #   person.pets.destroy("4")
+      #   # => #<Pet id: 4, name: "Benny", person_id: 1>
+      #
+      #   person.pets.size # => 2
+      #   person.pets
+      #   # => [
+      #   #       #<Pet id: 5, name: "Brain", person_id: 1>,
+      #   #       #<Pet id: 6, name: "Boss",  person_id: 1>
+      #   #    ]
+      #
+      #   person.pets.destroy(5, 6)
+      #   # => [
+      #   #       #<Pet id: 5, name: "Brain", person_id: 1>,
+      #   #       #<Pet id: 6, name: "Boss",  person_id: 1>
+      #   #    ]
+      #
+      #   person.pets.size  # => 0
+      #   person.pets       # => []
+      #
+      #   Pet.find(4, 5, 6) # => ActiveRecord::RecordNotFound: Couldn't find all Pets with IDs (4, 5, 6)
 
       ##
       # :method: empty?
@@ -298,7 +330,7 @@ class CollectionProxy < Relation
       #
       #   person.pets.count  # => 0
       #   person.pets.empty? # => true
-      
+
       ##
       # :method: any?
       # Returns true if the collection is not empty.