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, 22 insertions, 21 deletions

diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
index eb1aece32d..bceda5abd9 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
@@ -187,7 +187,7 @@ module ActiveRecord
     # Represents the schema of an SQL table in an abstract way. This class
     # provides methods for manipulating the schema representation.
     #
-    # Inside migration files, the +t+ object in +create_table+
+    # Inside migration files, the +t+ object in {create_table}[rdoc-ref:SchemaStatements#create_table]
     # is actually of this type:
     #
     #   class SomeMigration < ActiveRecord::Migration
@@ -203,7 +203,7 @@ module ActiveRecord
     #   end
     #
     # The table definitions
-    # The Columns are stored as a ColumnDefinition in the +columns+ attribute.
+    # The Columns are stored as a ColumnDefinition in the #columns attribute.
     class TableDefinition
       include ColumnMethods
 
@@ -321,7 +321,7 @@ module ActiveRecord
       #
       # == Short-hand examples
       #
-      # Instead of calling +column+ directly, you can also work with the short-hand definitions for the default types.
+      # Instead of calling #column directly, you can also work with the short-hand definitions for the default types.
       # They use the type as the method name instead of as a parameter and allow for multiple columns to be defined
       # in a single statement.
       #
@@ -353,7 +353,8 @@ module ActiveRecord
       # TableDefinition#references will add an appropriately-named _id column, plus a corresponding _type
       # column if the <tt>:polymorphic</tt> option is supplied. If <tt>:polymorphic</tt> is a hash of
       # options, these will be used when creating the <tt>_type</tt> column. The <tt>:index</tt> option
-      # will also create an index, similar to calling <tt>add_index</tt>. So what can be written like this:
+      # will also create an index, similar to calling {add_index}[rdoc-ref:ConnectionAdapters::SchemaStatements#add_index].
+      # So what can be written like this:
       #
       #   create_table :taggings do |t|
       #     t.integer :tag_id, :tagger_id, :taggable_id
@@ -404,7 +405,7 @@ module ActiveRecord
       end
 
       # Appends <tt>:datetime</tt> columns <tt>:created_at</tt> and
-      # <tt>:updated_at</tt> to the table. See SchemaStatements#add_timestamps
+      # <tt>:updated_at</tt> to the table. See {connection.add_timestamps}[rdoc-ref:SchemaStatements#add_timestamps]
       #
       #   t.timestamps null: false
       def timestamps(*args)
@@ -421,7 +422,7 @@ module ActiveRecord
       #  t.references(:user)
       #  t.belongs_to(:supplier, foreign_key: true)
       #
-      # See SchemaStatements#add_reference for details of the options you can use.
+      # See {connection.add_reference}[rdoc-ref:SchemaStatements#add_reference] for details of the options you can use.
       def references(*args, **options)
         args.each do |col|
           ReferenceDefinition.new(col, **options).add_to(self)
@@ -493,7 +494,7 @@ module ActiveRecord
     end
 
     # Represents an SQL table in an abstract way for updating a table.
-    # Also see TableDefinition and SchemaStatements#create_table
+    # Also see TableDefinition and {connection.create_table}[rdoc-ref:SchemaStatements#create_table]
     #
     # Available transformations are:
     #
@@ -550,7 +551,7 @@ module ActiveRecord
       #
       # t.string(:name) unless t.column_exists?(:name, :string)
       #
-      # See SchemaStatements#column_exists?
+      # See {connection.column_exists?}[rdoc-ref:SchemaStatements#column_exists?]
       def column_exists?(column_name, type = nil, options = {})
         @base.column_exists?(name, column_name, type, options)
       end
@@ -562,7 +563,7 @@ module ActiveRecord
       #  t.index([:branch_id, :party_id], unique: true)
       #  t.index([:branch_id, :party_id], unique: true, name: 'by_branch_party')
       #
-      # See SchemaStatements#add_index for details of the options you can use.
+      # See {connection.add_index}[rdoc-ref:SchemaStatements#add_index] for details of the options you can use.
       def index(column_name, options = {})
         @base.add_index(name, column_name, options)
       end
@@ -573,7 +574,7 @@ module ActiveRecord
       #   t.index(:branch_id)
       # end
       #
-      # See SchemaStatements#index_exists?
+      # See {connection.index_exists?}[rdoc-ref:SchemaStatements#index_exists?]
       def index_exists?(column_name, options = {})
         @base.index_exists?(name, column_name, options)
       end
@@ -582,7 +583,7 @@ module ActiveRecord
       #
       #  t.rename_index(:user_id, :account_id)
       #
-      # See SchemaStatements#rename_index
+      # See {connection.rename_index}[rdoc-ref:SchemaStatements#rename_index]
       def rename_index(index_name, new_index_name)
         @base.rename_index(name, index_name, new_index_name)
       end
@@ -591,7 +592,7 @@ module ActiveRecord
       #
       #  t.timestamps(null: false)
       #
-      # See SchemaStatements#add_timestamps
+      # See {connection.add_timestamps}[rdoc-ref:SchemaStatements#add_timestamps]
       def timestamps(options = {})
         @base.add_timestamps(name, options)
       end
@@ -612,7 +613,7 @@ module ActiveRecord
       #  t.change_default(:authorized, 1)
       #  t.change_default(:status, from: nil, to: "draft")
       #
-      # See SchemaStatements#change_column_default
+      # See {connection.change_column_default}[rdoc-ref:SchemaStatements#change_column_default]
       def change_default(column_name, default_or_changes)
         @base.change_column_default(name, column_name, default_or_changes)
       end
@@ -622,7 +623,7 @@ module ActiveRecord
       #  t.remove(:qualification)
       #  t.remove(:qualification, :experience)
       #
-      # See SchemaStatements#remove_columns
+      # See {connection.remove_columns}[rdoc-ref:SchemaStatements#remove_columns]
       def remove(*column_names)
         @base.remove_columns(name, *column_names)
       end
@@ -633,7 +634,7 @@ module ActiveRecord
       #   t.remove_index(column: [:branch_id, :party_id])
       #   t.remove_index(name: :by_branch_party)
       #
-      # See SchemaStatements#remove_index
+      # See {connection.remove_index}[rdoc-ref:SchemaStatements#remove_index]
       def remove_index(options = {})
         @base.remove_index(name, options)
       end
@@ -642,7 +643,7 @@ module ActiveRecord
       #
       #  t.remove_timestamps
       #
-      # See SchemaStatements#remove_timestamps
+      # See {connection.remove_timestamps}[rdoc-ref:SchemaStatements#remove_timestamps]
       def remove_timestamps(options = {})
         @base.remove_timestamps(name, options)
       end
@@ -651,7 +652,7 @@ module ActiveRecord
       #
       #  t.rename(:description, :name)
       #
-      # See SchemaStatements#rename_column
+      # See {connection.rename_column}[rdoc-ref:SchemaStatements#rename_column]
       def rename(column_name, new_column_name)
         @base.rename_column(name, column_name, new_column_name)
       end
@@ -661,7 +662,7 @@ module ActiveRecord
       #  t.references(:user)
       #  t.belongs_to(:supplier, foreign_key: true)
       #
-      # See SchemaStatements#add_reference for details of the options you can use.
+      # See {connection.add_reference}[rdoc-ref:SchemaStatements#add_reference] for details of the options you can use.
       def references(*args)
         options = args.extract_options!
         args.each do |ref_name|
@@ -675,7 +676,7 @@ module ActiveRecord
       #  t.remove_references(:user)
       #  t.remove_belongs_to(:supplier, polymorphic: true)
       #
-      # See SchemaStatements#remove_reference
+      # See {connection.remove_reference}[rdoc-ref:SchemaStatements#remove_reference]
       def remove_references(*args)
         options = args.extract_options!
         args.each do |ref_name|
@@ -688,7 +689,7 @@ module ActiveRecord
       #
       # t.foreign_key(:authors)
       #
-      # See SchemaStatements#add_foreign_key
+      # See {connection.add_foreign_key}[rdoc-ref:SchemaStatements#add_foreign_key]
       def foreign_key(*args) # :nodoc:
         @base.add_foreign_key(name, *args)
       end
@@ -697,7 +698,7 @@ module ActiveRecord
       #
       # t.foreign_key(:authors) unless t.foreign_key_exists?(:authors)
       #
-      # See SchemaStatements#foreign_key_exists?
+      # See {connection.foreign_key_exists?}[rdoc-ref:SchemaStatements#foreign_key_exists?]
       def foreign_key_exists?(*args) # :nodoc:
         @base.foreign_key_exists?(name, *args)
       end