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

diff --git a/activerecord/lib/active_record/callbacks.rb b/activerecord/lib/active_record/callbacks.rb
index 60b1ff07dc..bfedc4af3f 100644
--- a/activerecord/lib/active_record/callbacks.rb
+++ b/activerecord/lib/active_record/callbacks.rb
@@ -1,11 +1,11 @@
 module ActiveRecord
-  # = Active Record Callbacks
+  # = Active Record \Callbacks
   #
-  # Callbacks are hooks into the life cycle of an Active Record object that allow you to trigger logic
+  # \Callbacks are hooks into the life cycle of an Active Record object that allow you to trigger logic
   # before or after an alteration of the object state. This can be used to make sure that associated and
-  # dependent objects are deleted when +destroy+ is called (by overwriting +before_destroy+) or to massage attributes
-  # before they're validated (by overwriting +before_validation+). As an example of the callbacks initiated, consider
-  # the <tt>Base#save</tt> call for a new record:
+  # dependent objects are deleted when {ActiveRecord::Base#destroy}[rdoc-ref:Persistence#destroy] is called (by overwriting +before_destroy+) or
+  # to massage attributes before they're validated (by overwriting +before_validation+).
+  # As an example of the callbacks initiated, consider the {ActiveRecord::Base#save}[rdoc-ref:Persistence#save] call for a new record:
   #
   # * (-) <tt>save</tt>
   # * (-) <tt>valid</tt>
@@ -20,7 +20,7 @@ module ActiveRecord
   # * (7) <tt>after_commit</tt>
   #
   # Also, an <tt>after_rollback</tt> callback can be configured to be triggered whenever a rollback is issued.
-  # Check out <tt>ActiveRecord::Transactions</tt> for more details about <tt>after_commit</tt> and
+  # Check out ActiveRecord::Transactions for more details about <tt>after_commit</tt> and
   # <tt>after_rollback</tt>.
   #
   # Additionally, an <tt>after_touch</tt> callback is triggered whenever an
@@ -31,7 +31,7 @@ module ActiveRecord
   # are instantiated as well.
   #
   # There are nineteen callbacks in total, which give you immense power to react and prepare for each state in the
-  # Active Record life cycle. The sequence for calling <tt>Base#save</tt> for an existing record is similar,
+  # Active Record life cycle. The sequence for calling {ActiveRecord::Base#save}[rdoc-ref:Persistence#save] for an existing record is similar,
   # except that each <tt>_create</tt> callback is replaced by the corresponding <tt>_update</tt> callback.
   #
   # Examples:
@@ -193,8 +193,9 @@ module ActiveRecord
   # == <tt>before_validation*</tt> returning statements
   #
   # If the +before_validation+ callback throws +:abort+, the process will be
-  # aborted and <tt>Base#save</tt> will return +false+. If Base#save! is called it will raise a
-  # <tt>ActiveRecord::RecordInvalid</tt> exception. Nothing will be appended to the errors object.
+  # aborted and {ActiveRecord::Base#save}[rdoc-ref:Persistence#save] will return +false+.
+  # If {ActiveRecord::Base#save!}[rdoc-ref:Persistence#save!] is called it will raise a ActiveRecord::RecordInvalid exception.
+  # Nothing will be appended to the errors object.
   #
   # == Canceling callbacks
   #
@@ -223,7 +224,8 @@ module ActiveRecord
   #   end
   #
   # In this case, the problem is that when the +before_destroy+ callback is executed, the children are not available
-  # because the +destroy+ callback gets executed first. You can use the +prepend+ option on the +before_destroy+ callback to avoid this.
+  # because the {ActiveRecord::Base#destroy}[rdoc-ref:Persistence#destroy] callback gets executed first.
+  # You can use the +prepend+ option on the +before_destroy+ callback to avoid this.
   #
   #   class Topic < ActiveRecord::Base
   #     has_many :children, dependent: destroy
@@ -238,21 +240,21 @@ module ActiveRecord
   #
   # This way, the +before_destroy+ gets executed before the <tt>dependent: destroy</tt> is called, and the data is still available.
   #
-  # == Transactions
+  # == \Transactions
   #
-  # The entire callback chain of a +save+, <tt>save!</tt>, or +destroy+ call runs
-  # within a transaction. That includes <tt>after_*</tt> hooks. If everything
-  # goes fine a COMMIT is executed once the chain has been completed.
+  # The entire callback chain of a {#save}[rdoc-ref:Persistence#save], {#save!}[rdoc-ref:Persistence#save!],
+  # or {#destroy}[rdoc-ref:Persistence#destroy] call runs within a transaction. That includes <tt>after_*</tt> hooks.
+  # If everything goes fine a COMMIT is executed once the chain has been completed.
   #
   # If a <tt>before_*</tt> callback cancels the action a ROLLBACK is issued. You
   # can also trigger a ROLLBACK raising an exception in any of the callbacks,
   # including <tt>after_*</tt> hooks. Note, however, that in that case the client
-  # needs to be aware of it because an ordinary +save+ will raise such exception
+  # needs to be aware of it because an ordinary {#save}[rdoc-ref:Persistence#save] will raise such exception
   # instead of quietly returning +false+.
   #
   # == Debugging callbacks
   #
-  # The callback chain is accessible via the <tt>_*_callbacks</tt> method on an object. ActiveModel Callbacks support
+  # The callback chain is accessible via the <tt>_*_callbacks</tt> method on an object. Active Model \Callbacks support
   # <tt>:before</tt>, <tt>:after</tt> and <tt>:around</tt> as values for the <tt>kind</tt> property. The <tt>kind</tt> property
   # defines what part of the chain the callback runs in.
   #