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

Conflicts:
	guides/source/migrations.md

1 files changed, 10 insertions, 8 deletions

diff --git a/activerecord/lib/active_record/counter_cache.rb b/activerecord/lib/active_record/counter_cache.rb
index c53b7b3e78..81f92db271 100644
--- a/activerecord/lib/active_record/counter_cache.rb
+++ b/activerecord/lib/active_record/counter_cache.rb
@@ -79,16 +79,17 @@ module ActiveRecord
         where(primary_key => id).update_all updates.join(', ')
       end
 
-      # Increment a number field by one, usually representing a count.
+      # Increment a numeric field by one, via a direct SQL update.
       #
-      # This is used for caching aggregate values, so that they don't need to be computed every time.
-      # For example, a DiscussionBoard may cache post_count and comment_count otherwise every time the board is
-      # shown it would have to run an SQL query to find how many posts and comments there are.
+      # This method is used primarily for maintaining counter_cache columns used to
+      # store aggregate values. For example, a DiscussionBoard may cache posts_count
+      # and comments_count to avoid running an SQL query to calculate the number of
+      # posts and comments there are each time it is displayed.
       #
       # ==== Parameters
       #
       # * +counter_name+ - The name of the field that should be incremented.
-      # * +id+ - The id of the object that should be incremented.
+      # * +id+ - The id of the object that should be incremented or an Array of ids.
       #
       # ==== Examples
       #
@@ -98,14 +99,15 @@ module ActiveRecord
         update_counters(id, counter_name => 1)
       end
 
-      # Decrement a number field by one, usually representing a count.
+      # Decrement a numeric field by one, via a direct SQL update.
       #
-      # This works the same as increment_counter but reduces the column value by 1 instead of increasing it.
+      # This works the same as increment_counter but reduces the column value by
+      # 1 instead of increasing it.
       #
       # ==== Parameters
       #
       # * +counter_name+ - The name of the field that should be decremented.
-      # * +id+ - The id of the object that should be decremented.
+      # * +id+ - The id of the object that should be decremented or an Array of ids.
       #
       # ==== Examples
       #