Corrected documentation of has_many methods collection.build and collection.create.

* collection.create: Clarified the wording (this had always confused me). I used the phrase
"base model" to mean the model that specifies the has_many association (this wording is also
used previously, e.g. in the "Cardinality and associations" section).

* collection.build: You *can* actually call this to add new association records when the base
model is a new record. In ActiveRecord::Associations::AssociationCollection, #create_record
calls #ensure_owner_is_not_new, but #build_record does not.

1 files changed, 3 insertions, 4 deletions

diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb
index 0539aa4db2..56d13a4303 100755
--- a/activerecord/lib/active_record/associations.rb
+++ b/activerecord/lib/active_record/associations.rb
@@ -767,13 +767,12 @@ module ActiveRecord
       # [collection.build(attributes = {}, ...)]
       #   Returns one or more new objects of the collection type that have been instantiated
       #   with +attributes+ and linked to this object through a foreign key, but have not yet
-      #   been saved. <b>Note:</b> This only works if an associated object already exists, not if
-      #   it's +nil+!
+      #   been saved.
       # [collection.create(attributes = {})]
       #   Returns a new object of the collection type that has been instantiated
       #   with +attributes+, linked to this object through a foreign key, and that has already
-      #   been saved (if it passed the validation). <b>Note:</b> This only works if an associated
-      #   object already exists, not if it's +nil+!
+      #   been saved (if it passed the validation). *Note*: This only works if the base model
+      #   already exists, not if it's +nil+ or is a new (unsaved) record!
       #
       # (*Note*: +collection+ is replaced with the symbol passed as the first argument, so
       # <tt>has_many :clients</tt> would add among others <tt>clients.empty?</tt>.)