Modified comments explaining what the update_only option does.

Author: Mark

activerecord/lib/active_record/nested_attributes.rb

@@ -248,10 +248,18 @@ module ClassMethods
       #   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 @@ def _destroy
 
     # 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,