Merge branch 'master' of github.com:lifo/docrails

4 files changed, 305 insertions, 23 deletions

diff --git a/activerecord/lib/active_record/associations/collection_association.rb b/activerecord/lib/active_record/associations/collection_association.rb
index 8dbcf8b225..4ec176e641 100644
--- a/activerecord/lib/active_record/associations/collection_association.rb
+++ b/activerecord/lib/active_record/associations/collection_association.rb
@@ -6,6 +6,15 @@ module ActiveRecord
     # ease the implementation of association proxies that represent
     # collections. See the class hierarchy in AssociationProxy.
     #
+    #   CollectionAssociation:
+    #     HasAndBelongsToManyAssociation => has_and_belongs_to_many
+    #     HasManyAssociation => has_many
+    #       HasManyThroughAssociation + ThroughAssociation => has_many :through
+    #
+    # CollectionAssociation class provides common methods to the collections
+    # defined by +has_and_belongs_to_many+, +has_many+ or +has_many+ with
+    # +:through association+ option.
+    #
     # You need to be careful with assumptions regarding the target: The proxy
     # does not fetch records from the database until it needs them, but new
     # ones created with +build+ are added to the target. So, the target may be
@@ -115,8 +124,9 @@ module ActiveRecord
         create_record(attributes, options, true, &block)
       end
 
-      # Add +records+ to this association. Returns +self+ so method calls may be chained.
-      # Since << flattens its argument list and inserts each record, +push+ and +concat+ behave identically.
+      # Add +records+ to this association. Returns +self+ so method calls may
+      # be chained. Since << flattens its argument list and inserts each record,
+      # +push+ and +concat+ behave identically.
       def concat(*records)
         load_target if owner.new_record?
 
@@ -142,7 +152,7 @@ module ActiveRecord
         end
       end
 
-      # Remove all records from this association
+      # Remove all records from this association.
       #
       # See delete for more info.
       def delete_all
@@ -162,7 +172,7 @@ module ActiveRecord
         end
       end
 
-      # Calculate sum using SQL, not Enumerable
+      # Calculate sum using SQL, not Enumerable.
       def sum(*args)
         if block_given?
           scoped.sum(*args) { |*block_args| yield(*block_args) }
@@ -270,13 +280,16 @@ module ActiveRecord
         load_target.size
       end
 
-      # Equivalent to <tt>collection.size.zero?</tt>. If the collection has
-      # not been already loaded and you are going to fetch the records anyway
-      # it is better to check <tt>collection.length.zero?</tt>.
+      # Returns true if the collection is empty. Equivalent to
+      # <tt>collection.size.zero?</tt>. If the collection has not been already
+      # loaded and you are going to fetch the records anyway it is better to
+      # check <tt>collection.length.zero?</tt>.
       def empty?
         size.zero?
       end
 
+      # Returns true if the collections is not empty.
+      # Equivalent to +!collection.empty?+.
       def any?
         if block_given?
           load_target.any? { |*block_args| yield(*block_args) }
@@ -285,7 +298,8 @@ module ActiveRecord
         end
       end
 
-      # Returns true if the collection has more than 1 record. Equivalent to collection.size > 1.
+      # Returns true if the collection has more than 1 record.
+      # Equivalent to +collection.size > 1+.
       def many?
         if block_given?
           load_target.many? { |*block_args| yield(*block_args) }
@@ -301,8 +315,8 @@ module ActiveRecord
         end
       end
 
-      # Replace this collection with +other_array+
-      # This will perform a diff and delete/add only records that have changed.
+      # Replace this collection with +other_array+. This will perform a diff
+      # and delete/add only records that have changed.
       def replace(other_array)
         other_array.each { |val| raise_on_type_mismatch(val) }
         original_target = load_target.dup
diff --git a/activerecord/lib/active_record/associations/collection_proxy.rb b/activerecord/lib/active_record/associations/collection_proxy.rb
index cf4cc98f38..fa316a8c9d 100644
--- a/activerecord/lib/active_record/associations/collection_proxy.rb
+++ b/activerecord/lib/active_record/associations/collection_proxy.rb
@@ -33,9 +33,231 @@ module ActiveRecord
     #
     # is computed directly through SQL and does not trigger by itself the
     # instantiation of the actual post records.
-    class CollectionProxy < Relation # :nodoc:
+    class CollectionProxy < Relation
       delegate :target, :load_target, :loaded?, :to => :@association
 
+      ##
+      # :method: first
+      # Returns the first record, or the first +n+ records, from the collection.
+      # If the collection is empty, the first form returns nil, and the second
+      # form returns an empty array.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets
+      #   # => [
+      #   #       #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>,
+      #   #       #<Pet id: 2, name: "Spook", person_id: 1>,
+      #   #       #<Pet id: 3, name: "Choo-Choo", person_id: 1>
+      #   #    ]
+      #
+      #   person.pets.first # => #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>
+      #
+      #   person.pets.first(2)
+      #   # => [
+      #   #      #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>,
+      #   #      #<Pet id: 2, name: "Spook", person_id: 1>
+      #   #    ]
+      #
+      #   another_person_without.pets          # => []
+      #   another_person_without.pets.first    # => nil
+      #   another_person_without.pets.first(3) # => []
+
+      ##
+      # :method: last
+      # Returns the last record, or the last +n+ records, from the collection.
+      # If the collection is empty, the first form returns nil, and the second
+      # form returns an empty array.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets
+      #   # => [
+      #   #       #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>,
+      #   #       #<Pet id: 2, name: "Spook", person_id: 1>,
+      #   #       #<Pet id: 3, name: "Choo-Choo", person_id: 1>
+      #   #    ]
+      #
+      #   person.pets.last # => #<Pet id: 3, name: "Choo-Choo", person_id: 1>
+      #
+      #   person.pets.last(2)
+      #   # => [
+      #   #      #<Pet id: 2, name: "Spook", person_id: 1>,
+      #   #      #<Pet id: 3, name: "Choo-Choo", person_id: 1>
+      #   #    ]
+      #
+      #   another_person_without.pets         # => []
+      #   another_person_without.pets.last    # => nil
+      #   another_person_without.pets.last(3) # => []
+
+      ##
+      # :method: concat
+      # Add one or more records to the collection by setting their foreign keys
+      # to the association's primary key. Since << flattens its argument list and
+      # inserts each record, +push+ and +concat+ behave identically. Returns +self+
+      # so method calls may be chained.
+      #
+      #   class Person < ActiveRecord::Base
+      #     pets :has_many
+      #   end
+      #
+      #   person.pets.size # => 0
+      #   person.pets.concat(Pet.new(name: 'Fancy-Fancy'))
+      #   person.pets.concat(Pet.new(name: 'Spook'), Pet.new(name: 'Choo-Choo'))
+      #   person.pets.size # => 3
+      #
+      #   person.id # => 1
+      #   person.pets
+      #   # => [
+      #   #       #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>,
+      #   #       #<Pet id: 2, name: "Spook", person_id: 1>,
+      #   #       #<Pet id: 3, name: "Choo-Choo", person_id: 1>
+      #   #    ]
+      #
+      #   person.pets.concat([Pet.new(name: 'Brain'), Pet.new(name: 'Benny')])
+      #   person.pets.size # => 5
+
+      ##
+      # :method: replace
+      # Replace this collection with +other_array+. This will perform a diff
+      # and delete/add only records that have changed.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets
+      #   # => [#<Pet id: 1, name: "Gorby", group: "cats", person_id: 1>]
+      #
+      #   other_pets = [Pet.new(name: 'Puff', group: 'celebrities']
+      #
+      #   person.pets.replace(other_pets)
+      #
+      #   person.pets
+      #   # => [#<Pet id: 2, name: "Puff", group: "celebrities", person_id: 1>]
+      #
+      # If the supplied array has an incorrect association type, it raises
+      # an <tt>ActiveRecord::AssociationTypeMismatch</tt> error:
+      #
+      #   person.pets.replace(["doo", "ggie", "gaga"])
+      #   # => ActiveRecord::AssociationTypeMismatch: Pet expected, got String
+
+      ##
+      # :method: destroy_all
+      # Destroy all the records from this association.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets.size # => 3
+      #
+      #   person.pets.destroy_all
+      #
+      #   person.pets.size # => 0
+      #   person.pets      # => []
+
+      ##
+      # :method: empty?
+      # Returns true if the collection is empty.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets.count  # => 1
+      #   person.pets.empty? # => false
+      #
+      #   person.pets.delete_all
+      #
+      #   person.pets.count  # => 0
+      #   person.pets.empty? # => true
+
+      ##
+      # :method: any?
+      # Returns true if the collection is not empty.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets.count # => 0
+      #   person.pets.any?  # => false
+      #
+      #   person.pets << Pet.new(name: 'Snoop')
+      #   person.pets.count # => 0
+      #   person.pets.any?  # => true
+      #
+      # You can also pass a block to define criteria. The behaviour
+      # is the same, it returns true if the collection based on the
+      # criteria is not empty.
+      #
+      #   person.pets
+      #   # => [#<Pet name: "Snoop", group: "dogs">]
+      #
+      #   person.pets.any? do |pet|
+      #     pet.group == 'cats'
+      #   end
+      #   # => false
+      #
+      #   person.pets.any? do |pet|
+      #     pet.group == 'dogs'
+      #   end
+      #   # => true
+
+      ##
+      # :method: many?
+      # Returns true if the collection has more than one record.
+      # Equivalent to +collection.size > 1+.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets.count #=> 1
+      #   person.pets.many? #=> false
+      #
+      #   person.pets << Pet.new(name: 'Snoopy')
+      #   person.pets.count #=> 2
+      #   person.pets.many? #=> true
+      #
+      # You can also pass a block to define criteria. The
+      # behaviour is the same, it returns true if the collection
+      # based on the criteria has more than one record.
+      #
+      #   person.pets
+      #   # => [
+      #   #      #<Pet name: "Gorby", group: "cats">,
+      #   #      #<Pet name: "Puff", group: "cats">,
+      #   #      #<Pet name: "Snoop", group: "dogs">
+      #   #    ]
+      #
+      #   person.pets.many? do |pet|
+      #     pet.group == 'dogs'
+      #   end
+      #   # => false
+      #
+      #   person.pets.many? do |pet|
+      #     pet.group == 'cats'
+      #   end
+      #   # => true
+
+      ##
+      # :method: include?
+      # Returns true if the given object is present in the collection.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets # => [#<Pet id: 20, name: "Snoop">]
+      #
+      #   person.pets.include?(Pet.find(20)) # => true
+      #   person.pets.include?(Pet.find(21)) # => false
       delegate :select, :find, :first, :last,
                :build, :create, :create!,
                :concat, :replace, :delete_all, :destroy_all, :delete, :destroy, :uniq,
@@ -84,11 +306,57 @@ module ActiveRecord
       end
       alias_method :to_a, :to_ary
 
+      # Adds one or more +records+ to the collection by setting their foreign keys
+      # to the association‘s primary key. Returns +self+, so several appends may be
+      # chained together.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets.size # => 0
+      #   person.pets << Pet.new(name: 'Fancy-Fancy')
+      #   person.pets << [Pet.new(name: 'Spook'), Pet.new(name: 'Choo-Choo')]
+      #   person.pets.size # => 3
+      #
+      #   person.id # => 1
+      #   person.pets
+      #   # => [
+      #   #      #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>,
+      #   #      #<Pet id: 2, name: "Spook", person_id: 1>,
+      #   #      #<Pet id: 3, name: "Choo-Choo", person_id: 1>
+      #   #    ]
       def <<(*records)
         proxy_association.concat(records) && self
       end
       alias_method :push, :<<
 
+      # Removes every object from the collection. This does not destroy
+      # the objects, it sets their foreign keys to +NULL+. Returns +self+
+      # so methods can be chained.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets
+      #   end
+      #
+      #   person.pets       # => [#<Pet id: 1, name: "Snoop", group: "dogs", person_id: 1>]
+      #   person.pets.clear # => []
+      #   person.pets.size  # => 0
+      #
+      #   Pet.find(1) # => #<Pet id: 1, name: "Snoop", group: "dogs", person_id: nil>
+      #
+      # If they are associated with +dependent: :destroy+ option, it deletes
+      # them directly from the database.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_many :pets, dependent: :destroy
+      #   end
+      #
+      #   person.pets       # => [#<Pet id: 2, name: "Gorby", group: "cats", person_id: 2>]
+      #   person.pets.clear # => []
+      #   person.pets.size  # => 0
+      #
+      #   Pet.find(2) # => ActiveRecord::RecordNotFound: Couldn't find Pet with id=2
       def clear
         delete_all
         self
diff --git a/activerecord/lib/active_record/core.rb b/activerecord/lib/active_record/core.rb
index b2ed606e5f..f2833fbf3c 100644
--- a/activerecord/lib/active_record/core.rb
+++ b/activerecord/lib/active_record/core.rb
@@ -127,7 +127,7 @@ module ActiveRecord
         object.is_a?(self)
       end
 
-      # Returns an instance of <tt>Arel::Table</tt> loaded with the curent table name.
+      # Returns an instance of <tt>Arel::Table</tt> loaded with the current table name.
       #
       #   class Post < ActiveRecord::Base
       #     scope :published_and_commented, published.and(self.arel_table[:comments_count].gt(0))
diff --git a/activerecord/lib/active_record/relation.rb b/activerecord/lib/active_record/relation.rb
index 779e052e3c..05ced3299b 100644
--- a/activerecord/lib/active_record/relation.rb
+++ b/activerecord/lib/active_record/relation.rb
@@ -370,17 +370,12 @@ module ActiveRecord
       end
     end
 
-    # Deletes the records matching +conditions+ without instantiating the records first, and hence not
-    # calling the +destroy+ method nor invoking callbacks. This is a single SQL DELETE statement that
-    # goes straight to the database, much more efficient than +destroy_all+. Be careful with relations
-    # though, in particular <tt>:dependent</tt> rules defined on associations are not honored. Returns
-    # the number of rows affected.
-    #
-    # ==== Parameters
-    #
-    # * +conditions+ - Conditions are specified the same way as with +find+ method.
-    #
-    # ==== Example
+    # Deletes the records matching +conditions+ without instantiating the records
+    # first, and hence not calling the +destroy+ method nor invoking callbacks. This
+    # is a single SQL DELETE statement that goes straight to the database, much more
+    # efficient than +destroy_all+. Be careful with relations though, in particular
+    # <tt>:dependent</tt> rules defined on associations are not honored. Returns the
+    # number of rows affected.
     #
     #   Post.delete_all("person_id = 5 AND (category = 'Something' OR category = 'Else')")
     #   Post.delete_all(["person_id = ? AND (category = ? OR category = ?)", 5, 'Something', 'Else'])
@@ -389,6 +384,11 @@ module ActiveRecord
     # Both calls delete the affected posts all at once with a single DELETE statement.
     # If you need to destroy dependent associations or call your <tt>before_*</tt> or
     # +after_destroy+ callbacks, use the +destroy_all+ method instead.
+    #
+    # If a limit scope is supplied, +delete_all+ raises an ActiveRecord error:
+    #
+    #   Post.limit(100).delete_all
+    #   # => ActiveRecord::ActiveRecordError: delete_all doesn't support limit scope
     def delete_all(conditions = nil)
       raise ActiveRecordError.new("delete_all doesn't support limit scope") if self.limit_value