applies new doc guidelines to Active Record.

The focus of this change is to make the API more accessible.
References to method and classes should be linked to make it easy to
navigate around.

This patch makes exzessiv use of `rdoc-ref:` to provide more readable
docs. This makes it possible to document `ActiveRecord::Base#save` even
though the method is within a separate module
`ActiveRecord::Persistence`. The goal here is to bring the API closer to
the actual code that you would write.

This commit only deals with Active Record. The other gems will be
updated accordingly but in different commits. The pass through Active
Record is not completely finished yet. A follow up commit will change
the spots I haven't yet had the time to update.

/cc @fxn

1 files changed, 6 insertions, 6 deletions

diff --git a/activerecord/lib/active_record/counter_cache.rb b/activerecord/lib/active_record/counter_cache.rb
index 82596b63df..9e7d391c70 100644
--- a/activerecord/lib/active_record/counter_cache.rb
+++ b/activerecord/lib/active_record/counter_cache.rb
@@ -45,14 +45,14 @@ module ActiveRecord
       end
 
       # A generic "counter updater" implementation, intended primarily to be
-      # used by increment_counter and decrement_counter, but which may also
+      # used by #increment_counter and #decrement_counter, but which may also
       # be useful on its own. It simply does a direct SQL update for the record
       # with the given ID, altering the given hash of counters by the amount
       # given by the corresponding value:
       #
       # ==== Parameters
       #
-      # * +id+ - The id of the object you wish to update a counter on or an Array of ids.
+      # * +id+ - The id of the object you wish to update a counter on or an array of ids.
       # * +counters+ - A Hash containing the names of the fields
       #   to update as keys and the amount to update the field by as values.
       #
@@ -86,14 +86,14 @@ module ActiveRecord
       # Increment a numeric field by one, via a direct SQL update.
       #
       # This method is used primarily for maintaining counter_cache columns that are
-      # used to store aggregate values. For example, a DiscussionBoard may cache
+      # 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 or an Array of ids.
+      # * +id+ - The id of the object that should be incremented or an array of ids.
       #
       # ==== Examples
       #
@@ -105,13 +105,13 @@ module ActiveRecord
 
       # Decrement a numeric field by one, via a direct SQL update.
       #
-      # This works the same as increment_counter but reduces the column value by
+      # 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 or an Array of ids.
+      # * +id+ - The id of the object that should be decremented or an array of ids.
       #
       # ==== Examples
       #