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

3 files changed, 5 insertions, 5 deletions

diff --git a/activerecord/lib/active_record/attribute_methods/before_type_cast.rb b/activerecord/lib/active_record/attribute_methods/before_type_cast.rb
index 56c1898551..1db6776688 100644
--- a/activerecord/lib/active_record/attribute_methods/before_type_cast.rb
+++ b/activerecord/lib/active_record/attribute_methods/before_type_cast.rb
@@ -2,7 +2,7 @@ module ActiveRecord
   module AttributeMethods
     # = Active Record Attribute Methods Before Type Cast
     #
-    # <tt>ActiveRecord::AttributeMethods::BeforeTypeCast</tt> provides a way to
+    # ActiveRecord::AttributeMethods::BeforeTypeCast provides a way to
     # read the value of the attributes before typecasting and deserialization.
     #
     #   class Task < ActiveRecord::Base
diff --git a/activerecord/lib/active_record/attribute_methods/primary_key.rb b/activerecord/lib/active_record/attribute_methods/primary_key.rb
index c28374e4ab..0d5cb8b37c 100644
--- a/activerecord/lib/active_record/attribute_methods/primary_key.rb
+++ b/activerecord/lib/active_record/attribute_methods/primary_key.rb
@@ -5,7 +5,7 @@ module ActiveRecord
     module PrimaryKey
       extend ActiveSupport::Concern
 
-      # Returns this record's primary key value wrapped in an Array if one is
+      # Returns this record's primary key value wrapped in an array if one is
       # available.
       def to_key
         sync_with_transaction_state
@@ -108,7 +108,7 @@ module ActiveRecord
         #     self.primary_key = 'sysid'
         #   end
         #
-        # You can also define the +primary_key+ method yourself:
+        # You can also define the #primary_key method yourself:
         #
         #   class Project < ActiveRecord::Base
         #     def self.primary_key
diff --git a/activerecord/lib/active_record/attribute_methods/serialization.rb b/activerecord/lib/active_record/attribute_methods/serialization.rb
index 60eecab0d0..65978aea2a 100644
--- a/activerecord/lib/active_record/attribute_methods/serialization.rb
+++ b/activerecord/lib/active_record/attribute_methods/serialization.rb
@@ -9,7 +9,7 @@ module ActiveRecord
         # attribute using this method and it will be handled automatically. The
         # serialization is done through YAML. If +class_name+ is specified, the
         # serialized object must be of that class on assignment and retrieval.
-        # Otherwise <tt>SerializationTypeMismatch</tt> will be raised.
+        # Otherwise SerializationTypeMismatch will be raised.
         #
         # Empty objects as <tt>{}</tt>, in the case of +Hash+, or <tt>[]</tt>, in the case of
         # +Array+, will always be persisted as null.
@@ -17,7 +17,7 @@ module ActiveRecord
         # Keep in mind that database adapters handle certain serialization tasks
         # for you. For instance: +json+ and +jsonb+ types in PostgreSQL will be
         # converted between JSON object/array syntax and Ruby +Hash+ or +Array+
-        # objects transparently. There is no need to use +serialize+ in this
+        # objects transparently. There is no need to use #serialize in this
         # case.
         #
         # For more complex cases, such as conversion to or from your application