rails/rails — pull request #5212 by MarkMT (2012-02-28 22:13:19+00:00)
Title: update_only documentation for accepts_nested_attributes_for

I found the existing API documentation for the update_only option confusing and had to spend a lot of time studying the code to understand what it actually does. For example, when the existing comments say that update_only "allows you to specify that an existing record may only be updated", it's not clear what this is being contrasted with. Here's an [example](http://masonoise.wordpress.com/2010/07/23/rails-and-forms-using-accepts_nested_attributes_for/) blog post that illustrates someone else's confusion on exactly this point (see the second to last paragraph).

To understand the current description you also need to know (a) that the alternative to updating the record that the comment alludes to is to replace it with a new one, and (b) that in the default case the record is updated only if you supply a matching id, and replaced with a new one if you don't - again not something that is necessarily obvious.

The changes I have made are intended to address these points.