Merge branch 'master' of http://github.com/rails/rails

1 files changed, 15 insertions, 4 deletions

diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb
index 4caa434fc0..65daa8ffbe 100644
--- a/activerecord/lib/active_record/associations.rb
+++ b/activerecord/lib/active_record/associations.rb
@@ -763,20 +763,27 @@ module ActiveRecord
       #   An empty array is returned if none are found.
       # [collection<<(object, ...)]
       #   Adds one or more objects to the collection by setting their foreign keys to the collection's primary key.
+      #   Note that this operation instantly fires update sql without waiting for the save or update call on the 
+      #   parent object.
       # [collection.delete(object, ...)]
       #   Removes one or more objects from the collection by setting their foreign keys to +NULL+.
       #   Objects will be in addition destroyed if they're associated with <tt>:dependent => :destroy</tt>,
       #   and deleted if they're associated with <tt>:dependent => :delete_all</tt>.
       # [collection=objects]
-      #   Replaces the collections content by deleting and adding objects as appropriate.
+      #   Replaces the collections content by deleting and adding objects as appropriate. If the <tt>:through</tt>
+      #   option is true callbacks in the join models are triggered except destroy callbacks, since deletion is
+      #   direct.
       # [collection_singular_ids]
       #   Returns an array of the associated objects' ids
       # [collection_singular_ids=ids]
-      #   Replace the collection with the objects identified by the primary keys in +ids+
+      #   Replace the collection with the objects identified by the primary keys in +ids+. This
+      #   method loads the models and calls <tt>collection=</tt>. See above.
       # [collection.clear]
       #   Removes every object from the collection. This destroys the associated objects if they
       #   are associated with <tt>:dependent => :destroy</tt>, deletes them directly from the
       #   database if <tt>:dependent => :delete_all</tt>, otherwise sets their foreign keys to +NULL+.
+      #   If the <tt>:through</tt> option is true no destroy callbacks are invoked on the join models.
+      #   Join models are directly deleted.
       # [collection.empty?]
       #   Returns +true+ if there are no associated objects.
       # [collection.size]
@@ -869,9 +876,11 @@ module ActiveRecord
       # [:as]
       #   Specifies a polymorphic interface (See <tt>belongs_to</tt>).
       # [:through]
-      #   Specifies a Join Model through which to perform the query.  Options for <tt>:class_name</tt> and <tt>:foreign_key</tt>
+      #   Specifies a join model through which to perform the query.  Options for <tt>:class_name</tt> and <tt>:foreign_key</tt>
       #   are ignored, as the association uses the source reflection. You can only use a <tt>:through</tt> query through a <tt>belongs_to</tt>
-      #   <tt>has_one</tt> or <tt>has_many</tt> association on the join model.
+      #   <tt>has_one</tt> or <tt>has_many</tt> association on the join model. The collection of join models can be managed via the collection
+      #   API. For example, new join models are created for newly associated objects, and if some are gone their rows are deleted (directly,
+      #   no destroy callbacks are triggered).
       # [:source]
       #   Specifies the source association name used by <tt>has_many :through</tt> queries.  Only use it if the name cannot be
       #   inferred from the association.  <tt>has_many :subscribers, :through => :subscriptions</tt> will look for either <tt>:subscribers</tt> or
@@ -1186,6 +1195,8 @@ module ActiveRecord
       # [collection<<(object, ...)]
       #   Adds one or more objects to the collection by creating associations in the join table
       #   (<tt>collection.push</tt> and <tt>collection.concat</tt> are aliases to this method).
+      #   Note that this operation instantly fires update sql without waiting for the save or update call on the 
+      #   parent object.
       # [collection.delete(object, ...)]
       #   Removes one or more objects from the collection by removing their associations from the join table.
       #   This does not destroy the objects.