From 29463aa15dd670621ad0de861b5aa66feeb09ffa Mon Sep 17 00:00:00 2001 From: Francesco Rodriguez Date: Fri, 25 May 2012 22:08:59 -0500 Subject: add CollectionProxy#delete documentation --- .../active_record/associations/collection_proxy.rb | 105 ++++++++++++++++++++- 1 file changed, 104 insertions(+), 1 deletion(-) (limited to 'activerecord') diff --git a/activerecord/lib/active_record/associations/collection_proxy.rb b/activerecord/lib/active_record/associations/collection_proxy.rb index 100fb38dec..2b59b07eb2 100644 --- a/activerecord/lib/active_record/associations/collection_proxy.rb +++ b/activerecord/lib/active_record/associations/collection_proxy.rb @@ -343,6 +343,9 @@ module ActiveRecord ## # :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 :dependent # option. Returns an array with the deleted records. @@ -435,6 +438,9 @@ module ActiveRecord ## # :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 @@ module ActiveRecord # # 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 :dependent option. Returns an array with the + # deleted records. + # + # If no :dependent option is given, then it will follow the default + # strategy. The default strategy is :nullify. This sets the foreign + # keys to NULL. For, +has_many+ :through, 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 + # # => [ + # # #, + # # #, + # # # + # # ] + # + # person.pets.delete(Pet.find(1)) + # # => [#] + # + # person.pets.size # => 2 + # person.pets + # # => [ + # # #, + # # # + # # ] + # + # Pet.find(1) + # # => # + # + # If it is set to :destroy 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 + # # => [ + # # #, + # # #, + # # # + # # ] + # + # person.pets.delete([Pet.find(1), Pet.find(3)]) + # # => [ + # # #, + # # # + # # ] + # + # person.pets.size # => 1 + # person.pets + # # => [#] + # + # Pet.find(1, 3) + # # => ActiveRecord::RecordNotFound: Couldn't find all Pets with IDs (1, 3) + # + # If it is set to :delete_all, 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 + # # => [ + # # #, + # # #, + # # # + # # ] + # + # person.pets.delete(Pet.find(1)) + # # => [#] + # + # person.pets.size # => 2 + # person.pets + # # => [ + # # #, + # # # + # # ] + # + # 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. # -- cgit v1.2.3