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, 16 insertions, 15 deletions

diff --git a/activerecord/lib/active_record/relation/calculations.rb b/activerecord/lib/active_record/relation/calculations.rb
index ee078102ca..16d5774fec 100644
--- a/activerecord/lib/active_record/relation/calculations.rb
+++ b/activerecord/lib/active_record/relation/calculations.rb
@@ -14,33 +14,34 @@ module ActiveRecord
     #   Person.distinct.count(:age)
     #   # => counts the number of different age values
     #
-    # If +count+ is used with +group+, it returns a Hash whose keys represent the aggregated column,
+    # If #count is used with {Relation#group}[rdoc-ref:QueryMethods#group],
+    # it returns a Hash whose keys represent the aggregated column,
     # and the values are the respective amounts:
     #
     #   Person.group(:city).count
     #   # => { 'Rome' => 5, 'Paris' => 3 }
     #
-    # If +count+ is used with +group+ for multiple columns, it returns a Hash whose
+    # If #count is used with {Relation#group}[rdoc-ref:QueryMethods#group] for multiple columns, it returns a Hash whose
     # keys are an array containing the individual values of each column and the value
-    # of each key would be the +count+.
+    # of each key would be the #count.
     #
     #   Article.group(:status, :category).count
     #   # =>  {["draft", "business"]=>10, ["draft", "technology"]=>4,
     #          ["published", "business"]=>0, ["published", "technology"]=>2}
     #
-    # If +count+ is used with +select+, it will count the selected columns:
+    # If #count is used with {Relation#select}[rdoc-ref:QueryMethods#select], it will count the selected columns:
     #
     #   Person.select(:age).count
     #   # => counts the number of different age values
     #
-    # Note: not all valid +select+ expressions are valid +count+ expressions. The specifics differ
+    # Note: not all valid {Relation#select}[rdoc-ref:QueryMethods#select] expressions are valid #count expressions. The specifics differ
     # between databases. In invalid cases, an error from the database is thrown.
     def count(column_name = nil)
       calculate(:count, column_name)
     end
 
     # Calculates the average value on a given column. Returns +nil+ if there's
-    # no row. See +calculate+ for examples with options.
+    # no row. See #calculate for examples with options.
     #
     #   Person.average(:age) # => 35.8
     def average(column_name)
@@ -49,7 +50,7 @@ module ActiveRecord
 
     # Calculates the minimum value on a given column. The value is returned
     # with the same data type of the column, or +nil+ if there's no row. See
-    # +calculate+ for examples with options.
+    # #calculate for examples with options.
     #
     #   Person.minimum(:age) # => 7
     def minimum(column_name)
@@ -58,7 +59,7 @@ module ActiveRecord
 
     # Calculates the maximum value on a given column. The value is returned
     # with the same data type of the column, or +nil+ if there's no row. See
-    # +calculate+ for examples with options.
+    # #calculate for examples with options.
     #
     #   Person.maximum(:age) # => 93
     def maximum(column_name)
@@ -66,8 +67,8 @@ module ActiveRecord
     end
 
     # Calculates the sum of values on a given column. The value is returned
-    # with the same data type of the column, 0 if there's no row. See
-    # +calculate+ for examples with options.
+    # with the same data type of the column, +0+ if there's no row. See
+    # #calculate for examples with options.
     #
     #   Person.sum(:age) # => 4562
     def sum(column_name = nil, &block)
@@ -75,8 +76,8 @@ module ActiveRecord
       calculate(:sum, column_name)
     end
 
-    # This calculates aggregate values in the given column. Methods for count, sum, average,
-    # minimum, and maximum have been added as shortcuts.
+    # This calculates aggregate values in the given column. Methods for #count, #sum, #average,
+    # #minimum, and #maximum have been added as shortcuts.
     #
     #   Person.calculate(:count, :all) # The same as Person.count
     #   Person.average(:age) # SELECT AVG(age) FROM people...
@@ -118,7 +119,7 @@ module ActiveRecord
       end
     end
 
-    # Use <tt>pluck</tt> as a shortcut to select one or more attributes without
+    # Use #pluck as a shortcut to select one or more attributes without
     # loading a bunch of records just to grab the attributes you want.
     #
     #   Person.pluck(:name)
@@ -127,7 +128,7 @@ module ActiveRecord
     #
     #   Person.all.map(&:name)
     #
-    # Pluck returns an <tt>Array</tt> of attribute values type-casted to match
+    # Pluck returns an Array of attribute values type-casted to match
     # the plucked column names, if they can be deduced. Plucking an SQL fragment
     # returns String values by default.
     #
@@ -151,7 +152,7 @@ module ActiveRecord
     #   # SELECT DATEDIFF(updated_at, created_at) FROM people
     #   # => ['0', '27761', '173']
     #
-    # See also +ids+.
+    # See also #ids.
     #
     def pluck(*column_names)
       column_names.map! do |column_name|