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

4 files changed, 33 insertions, 23 deletions

diff --git a/activerecord/lib/active_record/associations/collection_proxy.rb b/activerecord/lib/active_record/associations/collection_proxy.rb
index 2176fc4e40..2fb80fdc4c 100644
--- a/activerecord/lib/active_record/associations/collection_proxy.rb
+++ b/activerecord/lib/active_record/associations/collection_proxy.rb
@@ -522,7 +522,7 @@ module ActiveRecord
       #   #       #<Pet id: 3, name: "Choo-Choo", person_id: 1>
       #   #    ]
       #
-      #   person.pets.delete([Pet.find(1), Pet.find(3)])
+      #   person.pets.delete(Pet.find(1), Pet.find(3))
       #   # => [
       #   #       #<Pet id: 1, name: "Fancy-Fancy", person_id: 1>,
       #   #       #<Pet id: 3, name: "Choo-Choo", person_id: 1>
diff --git a/activerecord/lib/active_record/relation/batches.rb b/activerecord/lib/active_record/relation/batches.rb
index 15f838a5ab..fb4388d4b2 100644
--- a/activerecord/lib/active_record/relation/batches.rb
+++ b/activerecord/lib/active_record/relation/batches.rb
@@ -2,20 +2,26 @@ require 'active_support/core_ext/object/blank'
 
 module ActiveRecord
   module Batches
-    # Yields each record that was found by the find +options+. The find is
-    # performed by find_in_batches with a batch size of 1000 (or as
+    # Looping through a collection of records from the database
+    # (using the +all+ method, for example) is very inefficient
+    # since it will try to instantiate all the objects at once.
+    #
+    # In that case, batch processing methods allow you to work
+    # with the records in batches, thereby greatly reducing memory consumption.
+    #
+    # The <tt>find_each</tt> method uses <tt>find_in_batches</tt> with a batch size of 1000 (or as
     # specified by the <tt>:batch_size</tt> option).
     #
-    # Example:
+    #   Person.all.find_each do |person|
+    #     person.do_awesome_stuff
+    #   end
     #
     #   Person.where("age > 21").find_each do |person|
     #     person.party_all_night!
     #   end
     #
-    # Note: This method is only intended to use for batch processing of
-    # large amounts of records that wouldn't fit in memory all at once. If
-    # you just need to loop over less than 1000 records, it's probably
-    # better just to use the regular find methods.
+    #  You can also pass the <tt>:start</tt> option to specify
+    #  an offset to control the starting point.
     def find_each(options = {})
       find_in_batches(options) do |records|
         records.each { |record| yield record }
@@ -39,12 +45,15 @@ module ActiveRecord
     # primary keys. You can't set the limit either, that's used to control
     # the batch sizes.
     #
-    # Example:
-    #
     #   Person.where("age > 21").find_in_batches do |group|
     #     sleep(50) # Make sure it doesn't get too crowded in there!
     #     group.each { |person| person.party_all_night! }
     #   end
+    #
+    #   # Let's process the next 2000 records
+    #   Person.all.find_in_batches(start: 2000, batch_size: 2000) do |group|
+    #     group.each { |person| person.party_all_night! }
+    #   end
     def find_in_batches(options = {})
       options.assert_valid_keys(:start, :batch_size)
 
diff --git a/activerecord/lib/active_record/relation/calculations.rb b/activerecord/lib/active_record/relation/calculations.rb
index 04b4fcf379..ad49c80e4f 100644
--- a/activerecord/lib/active_record/relation/calculations.rb
+++ b/activerecord/lib/active_record/relation/calculations.rb
@@ -129,7 +129,7 @@ module ActiveRecord
     #   Person.all.map(&:name)
     #
     # Pluck returns an <tt>Array</tt> of attribute values type-casted to match
-    # the plucked column name, if it can be deduced. Plucking a SQL fragment
+    # the plucked column name, if it can be deduced. Plucking an SQL fragment
     # returns String values by default.
     #
     # Examples:
diff --git a/activerecord/lib/active_record/relation/finder_methods.rb b/activerecord/lib/active_record/relation/finder_methods.rb
index 4fedd33d64..5f6898b45a 100644
--- a/activerecord/lib/active_record/relation/finder_methods.rb
+++ b/activerecord/lib/active_record/relation/finder_methods.rb
@@ -7,8 +7,6 @@ module ActiveRecord
     # If no record can be found for all of the listed ids, then RecordNotFound will be raised. If the primary key
     # is an integer, find by id coerces its arguments using +to_i+.
     #
-    # ==== Examples
-    #
     #   Person.find(1)       # returns the object for ID = 1
     #   Person.find("1")     # returns the object for ID = 1
     #   Person.find(1, 2, 6) # returns an array for objects with IDs in (1, 2, 6)
@@ -49,7 +47,6 @@ module ActiveRecord
     #
     #   Post.find_by name: 'Spartacus', rating: 4
     #   Post.find_by "published_at < ?", 2.weeks.ago
-    #
     def find_by(*args)
       where(*args).take
     end
@@ -64,8 +61,6 @@ module ActiveRecord
     # order. The order will depend on the database implementation.
     # If an order is supplied it will be respected.
     #
-    # Examples:
-    #
     #   Person.take # returns an object fetched by SELECT * FROM people
     #   Person.take(5) # returns 5 objects fetched by SELECT * FROM people LIMIT 5
     #   Person.where(["name LIKE '%?'", name]).take
@@ -82,12 +77,11 @@ module ActiveRecord
     # Find the first record (or first N records if a parameter is supplied).
     # If no order is defined it will order by primary key.
     #
-    # Examples:
-    #
     #   Person.first # returns the first object fetched by SELECT * FROM people
     #   Person.where(["user_name = ?", user_name]).first
     #   Person.where(["user_name = :u", { :u => user_name }]).first
     #   Person.order("created_on DESC").offset(5).first
+    #   Person.first(3) # returns the first three objects fetched by SELECT * FROM people LIMIT 3
     def first(limit = nil)
       if limit
         if order_values.empty? && primary_key
@@ -109,11 +103,18 @@ module ActiveRecord
     # Find the last record (or last N records if a parameter is supplied).
     # If no order is defined it will order by primary key.
     #
-    # Examples:
-    #
     #   Person.last # returns the last object fetched by SELECT * FROM people
     #   Person.where(["user_name = ?", user_name]).last
     #   Person.order("created_on DESC").offset(5).last
+    #   Person.last(3) # returns the last three objects fetched by SELECT * FROM people. 
+    #
+    # Take note that in that last case, the results are sorted in ascending order:
+    #
+    #   [#<Person id:2>, #<Person id:3>, #<Person id:4>]
+    #
+    # and not:
+    #
+    #   [#<Person id:4>, #<Person id:3>, #<Person id:2>]
     def last(limit = nil)
       if limit
         if order_values.empty? && primary_key
@@ -132,7 +133,8 @@ module ActiveRecord
       last or raise RecordNotFound
     end
 
-    # Examples:
+    # Runs the query on the database and returns records with the used query
+    # methods.
     #
     #   Person.all # returns an array of objects for all the rows fetched by SELECT * FROM people
     #   Person.where(["category IN (?)", categories]).limit(50).all
@@ -163,11 +165,10 @@ module ActiveRecord
     # 'Jamie'</tt>), since it would be sanitized and then queried against
     # the primary key column, like <tt>id = 'name = \'Jamie\''</tt>.
     #
-    # ==== Examples
     #   Person.exists?(5)
     #   Person.exists?('5')
-    #   Person.exists?(:name => "David")
     #   Person.exists?(['name LIKE ?', "%#{query}%"])
+    #   Person.exists?(:name => "David")
     #   Person.exists?
     def exists?(id = false)
       id = id.id if ActiveRecord::Model === id