Enhance documentation for decrement_counter. Closes #8093. [fearoffish]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@6683 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

2 files changed, 15 insertions, 1 deletions

diff --git a/activerecord/CHANGELOG b/activerecord/CHANGELOG
index 291309ce5d..5cd21b65f6 100644
--- a/activerecord/CHANGELOG
+++ b/activerecord/CHANGELOG
@@ -1,5 +1,7 @@
 *SVN*
 
+* Enhance documentation for decrement_counter. [fearoffish]
+
 * Provide brief introduction to what optimistic locking is. [fearoffish]
 
 * Add documentation for :encoding option to mysql adapter. [marclove]
diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb
index d1e70ce04d..43879603e3 100755
--- a/activerecord/lib/active_record/base.rb
+++ b/activerecord/lib/active_record/base.rb
@@ -564,7 +564,19 @@ module ActiveRecord #:nodoc:
         update_counters(id, counter_name => 1)
       end
 
-      # Works like increment_counter, but decrements instead.
+      # Decrement a number field by one, usually representing a count.
+      #
+      # This works the same as increment_counter but reduces the column value by 1 instead of increasing it.
+      #
+      # ==== Options
+      #
+      # +counter_name+  The name of the field that should be decremented
+      # +id+            The id of the object that should be decremented
+      #
+      # ==== Examples
+      #
+      #   # Decrement the post_count column for the record with an id of 5
+      #   DiscussionBoard.decrement_counter(:post_count, 5)
       def decrement_counter(counter_name, id)
         update_counters(id, counter_name => -1)
       end