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

5 files changed, 58 insertions, 55 deletions

diff --git a/activerecord/lib/active_record/relation/batches.rb b/activerecord/lib/active_record/relation/batches.rb
index beb8fa511c..221bc73680 100644
--- a/activerecord/lib/active_record/relation/batches.rb
+++ b/activerecord/lib/active_record/relation/batches.rb
@@ -3,8 +3,8 @@ require "active_record/relation/batches/batch_enumerator"
 module ActiveRecord
   module Batches
     # 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.
+    # (using the Scoping::Named::ClassMethods.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.
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|
diff --git a/activerecord/lib/active_record/relation/finder_methods.rb b/activerecord/lib/active_record/relation/finder_methods.rb
index 009b2bad57..435cef901b 100644
--- a/activerecord/lib/active_record/relation/finder_methods.rb
+++ b/activerecord/lib/active_record/relation/finder_methods.rb
@@ -17,7 +17,7 @@ module ActiveRecord
     #   Person.where("administrator = 1").order("created_on DESC").find(1)
     #
     # NOTE: The returned records may not be in the same order as the ids you
-    # provide since database rows are unordered. You'd need to provide an explicit <tt>order</tt>
+    # provide since database rows are unordered. You'd need to provide an explicit QueryMethods#order
     # option if you want the results are sorted.
     #
     # ==== Find with lock
@@ -34,7 +34,7 @@ module ActiveRecord
     #     person.save!
     #   end
     #
-    # ==== Variations of +find+
+    # ==== Variations of #find
     #
     #   Person.where(name: 'Spartacus', rating: 4)
     #   # returns a chainable list (which can be empty).
@@ -48,7 +48,7 @@ module ActiveRecord
     #   Person.where(name: 'Spartacus', rating: 4).first_or_create
     #   # returns the first item or creates it and returns it.
     #
-    # ==== Alternatives for +find+
+    # ==== Alternatives for #find
     #
     #   Person.where(name: 'Spartacus', rating: 4).exists?(conditions = :none)
     #   # returns a boolean indicating if any record with the given conditions exist.
@@ -80,8 +80,8 @@ module ActiveRecord
       nil
     end
 
-    # Like <tt>find_by</tt>, except that if no record is found, raises
-    # an <tt>ActiveRecord::RecordNotFound</tt> error.
+    # Like #find_by, except that if no record is found, raises
+    # an ActiveRecord::RecordNotFound error.
     def find_by!(arg, *args)
       where(arg, *args).take!
     rescue RangeError
@@ -100,8 +100,8 @@ module ActiveRecord
       limit ? limit(limit).to_a : find_take
     end
 
-    # Same as +take+ but raises <tt>ActiveRecord::RecordNotFound</tt> if no record
-    # is found. Note that <tt>take!</tt> accepts no arguments.
+    # Same as #take but raises ActiveRecord::RecordNotFound if no record
+    # is found. Note that #take! accepts no arguments.
     def take!
       take or raise RecordNotFound.new("Couldn't find #{@klass.name} with [#{arel.where_sql(@klass.arel_engine)}]")
     end
@@ -123,8 +123,8 @@ module ActiveRecord
       end
     end
 
-    # Same as +first+ but raises <tt>ActiveRecord::RecordNotFound</tt> if no record
-    # is found. Note that <tt>first!</tt> accepts no arguments.
+    # Same as #first but raises ActiveRecord::RecordNotFound if no record
+    # is found. Note that #first! accepts no arguments.
     def first!
       find_nth! 0
     end
@@ -156,8 +156,8 @@ module ActiveRecord
       end
     end
 
-    # Same as +last+ but raises <tt>ActiveRecord::RecordNotFound</tt> if no record
-    # is found. Note that <tt>last!</tt> accepts no arguments.
+    # Same as #last but raises ActiveRecord::RecordNotFound if no record
+    # is found. Note that #last! accepts no arguments.
     def last!
       last or raise RecordNotFound.new("Couldn't find #{@klass.name} with [#{arel.where_sql(@klass.arel_engine)}]")
     end
@@ -172,7 +172,7 @@ module ActiveRecord
       find_nth(1, offset_index)
     end
 
-    # Same as +second+ but raises <tt>ActiveRecord::RecordNotFound</tt> if no record
+    # Same as #second but raises ActiveRecord::RecordNotFound if no record
     # is found.
     def second!
       find_nth! 1
@@ -188,7 +188,7 @@ module ActiveRecord
       find_nth(2, offset_index)
     end
 
-    # Same as +third+ but raises <tt>ActiveRecord::RecordNotFound</tt> if no record
+    # Same as #third but raises ActiveRecord::RecordNotFound if no record
     # is found.
     def third!
       find_nth! 2
@@ -204,7 +204,7 @@ module ActiveRecord
       find_nth(3, offset_index)
     end
 
-    # Same as +fourth+ but raises <tt>ActiveRecord::RecordNotFound</tt> if no record
+    # Same as #fourth but raises ActiveRecord::RecordNotFound if no record
     # is found.
     def fourth!
       find_nth! 3
@@ -220,7 +220,7 @@ module ActiveRecord
       find_nth(4, offset_index)
     end
 
-    # Same as +fifth+ but raises <tt>ActiveRecord::RecordNotFound</tt> if no record
+    # Same as #fifth but raises ActiveRecord::RecordNotFound if no record
     # is found.
     def fifth!
       find_nth! 4
@@ -236,14 +236,14 @@ module ActiveRecord
       find_nth(41, offset_index)
     end
 
-    # Same as +forty_two+ but raises <tt>ActiveRecord::RecordNotFound</tt> if no record
+    # Same as #forty_two but raises ActiveRecord::RecordNotFound if no record
     # is found.
     def forty_two!
       find_nth! 41
     end
 
-    # Returns +true+ if a record exists in the table that matches the +id+ or
-    # conditions given, or +false+ otherwise. The argument can take six forms:
+    # Returns true if a record exists in the table that matches the +id+ or
+    # conditions given, or false otherwise. The argument can take six forms:
     #
     # * Integer - Finds the record with this primary key.
     # * String - Finds the record with a primary key corresponding to this
@@ -256,7 +256,7 @@ module ActiveRecord
     # * No args - Returns +false+ if the table is empty, +true+ otherwise.
     #
     # For more information about specifying conditions as a hash or array,
-    # see the Conditions section in the introduction to <tt>ActiveRecord::Base</tt>.
+    # see the Conditions section in the introduction to ActiveRecord::Base.
     #
     # Note: You can't pass in a condition as a string (like <tt>name =
     # 'Jamie'</tt>), since it would be sanitized and then queried against
@@ -298,7 +298,7 @@ module ActiveRecord
     end
 
     # This method is called whenever no records are found with either a single
-    # id or multiple ids and raises a +ActiveRecord::RecordNotFound+ exception.
+    # id or multiple ids and raises a ActiveRecord::RecordNotFound exception.
     #
     # The error message is different depending on whether a single id or
     # multiple ids are provided. If multiple ids are provided, then the number
diff --git a/activerecord/lib/active_record/relation/query_methods.rb b/activerecord/lib/active_record/relation/query_methods.rb
index 660bb0899a..55fd0e0b52 100644
--- a/activerecord/lib/active_record/relation/query_methods.rb
+++ b/activerecord/lib/active_record/relation/query_methods.rb
@@ -20,7 +20,7 @@ module ActiveRecord
       # Returns a new relation expressing WHERE + NOT condition according to
       # the conditions in the arguments.
       #
-      # +not+ accepts conditions as a string, array, or hash. See #where for
+      # #not accepts conditions as a string, array, or hash. See QueryMethods#where for
       # more details on each format.
       #
       #    User.where.not("name = 'Jon'")
@@ -112,7 +112,7 @@ module ActiveRecord
     #
     # allows you to access the +address+ attribute of the +User+ model without
     # firing an additional query. This will often result in a
-    # performance improvement over a simple +join+.
+    # performance improvement over a simple join.
     #
     # You can also specify multiple relationships, like this:
     #
@@ -133,7 +133,7 @@ module ActiveRecord
     #
     #   User.includes(:posts).where('posts.name = ?', 'example').references(:posts)
     #
-    # Note that +includes+ works with association names while +references+ needs
+    # Note that #includes works with association names while #references needs
     # the actual table name.
     def includes(*args)
       check_if_method_has_arguments!(:includes, args)
@@ -164,7 +164,7 @@ module ActiveRecord
       self
     end
 
-    # Allows preloading of +args+, in the same way that +includes+ does:
+    # Allows preloading of +args+, in the same way that #includes does:
     #
     #   User.preload(:posts)
     #   # SELECT "posts".* FROM "posts" WHERE "posts"."user_id" IN (1, 2, 3)
@@ -180,7 +180,7 @@ module ActiveRecord
 
     # Use to indicate that the given +table_names+ are referenced by an SQL string,
     # and should therefore be JOINed in any query rather than loaded separately.
-    # This method only works in conjunction with +includes+.
+    # This method only works in conjunction with #includes.
     # See #includes for more details.
     #
     #   User.includes(:posts).where("posts.name = 'foo'")
@@ -203,12 +203,12 @@ module ActiveRecord
 
     # Works in two unique ways.
     #
-    # First: takes a block so it can be used just like Array#select.
+    # First: takes a block so it can be used just like +Array#select+.
     #
     #   Model.all.select { |m| m.field == value }
     #
     # This will build an array of objects from the database for the scope,
-    # converting them into an array and iterating through them using Array#select.
+    # converting them into an array and iterating through them using +Array#select+.
     #
     # Second: Modifies the SELECT statement for the query so that only certain
     # fields are retrieved:
@@ -236,7 +236,7 @@ module ActiveRecord
     #   # => "value"
     #
     # Accessing attributes of an object that do not have fields retrieved by a select
-    # except +id+ will throw <tt>ActiveModel::MissingAttributeError</tt>:
+    # except +id+ will throw ActiveModel::MissingAttributeError:
     #
     #   Model.select(:field).first.other_field
     #   # => ActiveModel::MissingAttributeError: missing attribute: other_field
@@ -357,15 +357,15 @@ module ActiveRecord
     #   User.order('email DESC').select('id').where(name: "John")
     #       .unscope(:order, :select, :where) == User.all
     #
-    # One can additionally pass a hash as an argument to unscope specific :where values.
+    # One can additionally pass a hash as an argument to unscope specific +:where+ values.
     # This is done by passing a hash with a single key-value pair. The key should be
-    # :where and the value should be the where value to unscope. For example:
+    # +:where+ and the value should be the where value to unscope. For example:
     #
     #   User.where(name: "John", active: true).unscope(where: :name)
     #       == User.where(active: true)
     #
-    # This method is similar to <tt>except</tt>, but unlike
-    # <tt>except</tt>, it persists across merges:
+    # This method is similar to #except, but unlike
+    # #except, it persists across merges:
     #
     #   User.order('email').merge(User.except(:order))
     #       == User.order('email')
@@ -471,7 +471,7 @@ module ActiveRecord
     # than the previous methods; you are responsible for ensuring that the values in the template
     # are properly quoted. The values are passed to the connector for quoting, but the caller
     # is responsible for ensuring they are enclosed in quotes in the resulting SQL. After quoting,
-    # the values are inserted using the same escapes as the Ruby core method <tt>Kernel::sprintf</tt>.
+    # the values are inserted using the same escapes as the Ruby core method +Kernel::sprintf+.
     #
     #   User.where(["name = '%s' and email = '%s'", "Joe", "joe@example.com"])
     #   # SELECT * FROM users WHERE name = 'Joe' AND email = 'joe@example.com';
@@ -575,6 +575,8 @@ module ActiveRecord
     #   Post.where(active: true).where(trashed: true).rewhere(trashed: false)
     #   # WHERE `active` = 1 AND `trashed` = 0
     #
+    # This is short-hand for <tt>unscope(where: conditions.keys).where(conditions)</tt>.
+    # Note that unlike reorder, we're only unscoping the named conditions -- not the entire where statement.
     def rewhere(conditions)
       unscope(where: conditions.keys).where(conditions)
     end
@@ -583,8 +585,8 @@ module ActiveRecord
     # argument.
     #
     # The two relations must be structurally compatible: they must be scoping the same model, and
-    # they must differ only by +where+ (if no +group+ has been defined) or +having+ (if a +group+ is
-    # present). Neither relation may have a +limit+, +offset+, or +distinct+ set.
+    # they must differ only by #where (if no #group has been defined) or #having (if a #group is
+    # present). Neither relation may have a #limit, #offset, or #distinct set.
     #
     #    Post.where("id = 1").or(Post.where("id = 2"))
     #    # SELECT `posts`.* FROM `posts`  WHERE (('id = 1' OR 'id = 2'))
@@ -651,7 +653,7 @@ module ActiveRecord
     end
 
     # Specifies locking settings (default to +true+). For more information
-    # on locking, please see +ActiveRecord::Locking+.
+    # on locking, please see ActiveRecord::Locking.
     def lock(locks = true)
       spawn.lock!(locks)
     end
@@ -727,7 +729,7 @@ module ActiveRecord
     #   users = users.create_with(name: 'DHH')
     #   users.new.name # => 'DHH'
     #
-    # You can pass +nil+ to +create_with+ to reset attributes:
+    # You can pass +nil+ to #create_with to reset attributes:
     #
     #   users = users.create_with(nil)
     #   users.new.name # => 'Oscar'
diff --git a/activerecord/lib/active_record/relation/spawn_methods.rb b/activerecord/lib/active_record/relation/spawn_methods.rb
index 70da37fa84..5c3318651a 100644
--- a/activerecord/lib/active_record/relation/spawn_methods.rb
+++ b/activerecord/lib/active_record/relation/spawn_methods.rb
@@ -10,7 +10,7 @@ module ActiveRecord
       clone
     end
 
-    # Merges in the conditions from <tt>other</tt>, if <tt>other</tt> is an <tt>ActiveRecord::Relation</tt>.
+    # Merges in the conditions from <tt>other</tt>, if <tt>other</tt> is an ActiveRecord::Relation.
     # Returns an array representing the intersection of the resulting records with <tt>other</tt>, if <tt>other</tt> is an array.
     #   Post.where(published: true).joins(:comments).merge( Comment.where(spam: false) )
     #   # Performs a single join query with both where conditions.