From 2c62dd64dbaf1b3c758e7259fa8fefbafbbdcf81 Mon Sep 17 00:00:00 2001
From: Francesco Rodriguez <lrodriguezsanc@gmail.com>
Date: Tue, 22 May 2012 11:02:43 -0500
Subject: add CollectionProxy#build documentation

---
 .../active_record/associations/collection_proxy.rb | 31 ++++++++++++++++++++++
 1 file changed, 31 insertions(+)

(limited to 'activerecord/lib/active_record/associations')

diff --git a/activerecord/lib/active_record/associations/collection_proxy.rb b/activerecord/lib/active_record/associations/collection_proxy.rb
index 9ee69157b3..6c8fcec0c4 100644
--- a/activerecord/lib/active_record/associations/collection_proxy.rb
+++ b/activerecord/lib/active_record/associations/collection_proxy.rb
@@ -167,6 +167,37 @@ module ActiveRecord
       #   another_person_without.pets.last    # => nil
       #   another_person_without.pets.last(3) # => []
 
+      ##
+      # :method: build
+      #
+      # :call-seq:
+      #   build(attributes = {}, options = {}, &block)
+      #
+      # Returns a new object of the collection type that has been instantiated
+      # with +attributes+ and linked to this object, but have not yet been saved.
+      # You can pass an array of attributes hashes, this will return an array
+      # with the new objects.
+      #
+      #   class Person
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets.build
+      #   # => #<Pet id: nil, name: nil, person_id: 1>
+      #
+      #   person.pets.build(name: 'Fancy-Fancy')
+      #   # => #<Pet id: nil, name: "Fancy-Fancy", person_id: 1>
+      #
+      #   person.pets.build([{name: 'Spook'}, {name: 'Choo-Choo'}, {name: 'Brain'}])
+      #   # => [
+      #   #      #<Pet id: nil, name: "Spook", person_id: 1>,
+      #   #      #<Pet id: nil, name: "Choo-Choo", person_id: 1>,
+      #   #      #<Pet id: nil, name: "Brain", person_id: 1>
+      #   #    ]
+      #
+      #   person.pets.size  # => 5 # size of the collection
+      #   person.pets.count # => 0 # count from database
+
       ##
       # :method: concat
       # Add one or more records to the collection by setting their foreign keys
-- 
cgit v1.2.3