From 1f5c1a14236b2df638d20bcf1617110c47a4bfe8 Mon Sep 17 00:00:00 2001
From: Francesco Rodriguez <lrodriguezsanc@gmail.com>
Date: Mon, 21 May 2012 11:56:00 -0500
Subject: improve CollectionProxy#destroy documentation

---
 .../active_record/associations/collection_proxy.rb | 42 +++++++++++++++++++---
 1 file changed, 37 insertions(+), 5 deletions(-)

(limited to 'activerecord')

diff --git a/activerecord/lib/active_record/associations/collection_proxy.rb b/activerecord/lib/active_record/associations/collection_proxy.rb
index a3797e9d59..e3ebe03121 100644
--- a/activerecord/lib/active_record/associations/collection_proxy.rb
+++ b/activerecord/lib/active_record/associations/collection_proxy.rb
@@ -248,7 +248,7 @@ module ActiveRecord
       # :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 @@ module ActiveRecord
       #   #       #<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 @@ module ActiveRecord
       #
       #   person.pets.count  # => 0
       #   person.pets.empty? # => true
-      
+
       ##
       # :method: any?
       # Returns true if the collection is not empty.
-- 
cgit v1.2.3