From 27da612eeca83de3fd775b5460113f7b4eb12fad Mon Sep 17 00:00:00 2001
From: Mark <mark@rakino.(none)>
Date: Tue, 28 Feb 2012 14:28:44 -0600
Subject: Modified comments explaining what the update_only option does.

---
 .../lib/active_record/nested_attributes.rb         | 27 +++++++++++++++-------
 1 file changed, 19 insertions(+), 8 deletions(-)

(limited to 'activerecord/lib/active_record')

diff --git a/activerecord/lib/active_record/nested_attributes.rb b/activerecord/lib/active_record/nested_attributes.rb
index 9e21039c4f..6bf0becad8 100644
--- a/activerecord/lib/active_record/nested_attributes.rb
+++ b/activerecord/lib/active_record/nested_attributes.rb
@@ -248,10 +248,18 @@ module ActiveRecord
       #   exception is raised. If omitted, any number associations can be processed.
       #   Note that the :limit option is only applicable to one-to-many associations.
       # [:update_only]
-      #   Allows you to specify that an existing record may only be updated.
-      #   A new record may only be created when there is no existing record.
-      #   This option only works for one-to-one associations and is ignored for
-      #   collection associations. This option is off by default.
+      #   For a one-to-one association, this option allows you to specify how
+      #   nested attributes are to be used when an associated record already
+      #   exists. In general, an existing record may either be updated with the
+      #   new set of attribute values or be replaced by a wholly new record
+      #   containing those values. By default the :update_only option is +false+
+      #   and the nested attributes are used to update the existing record only
+      #   if they include the record's <tt>:id</tt> value. Otherwise a new
+      #   record will be instantiated and used to replace the existing one.
+      #   However if the :update_only option is +true+, the nested attributes
+      #   are used to update the record's attributes always, regardless of
+      #   whether the <tt>:id</tt> is present. The option is ignored for collection
+      #   associations.
       #
       # Examples:
       #   # creates avatar_attributes=
@@ -312,10 +320,13 @@ module ActiveRecord
 
     # Assigns the given attributes to the association.
     #
-    # If update_only is false and the given attributes include an <tt>:id</tt>
-    # that matches the existing record's id, then the existing record will be
-    # modified. If update_only is true, a new record is only created when no
-    # object exists. Otherwise a new record will be built.
+    # If an associated record does not yet exist, one will be instantiated. If
+    # an associated record already exists, the method's behavior depends on
+    # the value of the update_only option. If update_only is +false+ and the
+    # given attributes include an <tt>:id</tt> that matches the existing record's
+    # id, then the existing record will be modified. If no <tt>:id</tt> is provided
+    # it will be replaced with a new record. If update_only is +true+ the existing
+    # record will be modified regardless of whether an <tt>:id</tt> is provided.
     #
     # If the given attributes include a matching <tt>:id</tt> attribute, or
     # update_only is true, and a <tt>:_destroy</tt> key set to a truthy value,
-- 
cgit v1.2.3