better `add_reference` documentation. [ci skip]

This patch
  - reduces the duplication among the `reference`-family methods.
  - better explains all the optians available for `add_reference`.
  - redirects to user from `references` to `add_reference`.

Originated by #20184.

2 files changed, 18 insertions, 20 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 21321c9401..429445540d 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
@@ -402,17 +402,12 @@ module ActiveRecord
         column(:updated_at, :datetime, options)
       end
 
-      # Adds a reference. Optionally adds a +type+ column, if the
-      # +:polymorphic+ option is provided. +references+ and +belongs_to+
-      # are interchangeable. The reference column will be an +integer+ by default,
-      # the +:type+ option can be used to specify a different type. A foreign
-      # key will be created if the +:foreign_key+ option is passed.
+      # Adds a reference.
       #
       #  t.references(:user)
-      #  t.references(:user, type: "string")
-      #  t.belongs_to(:supplier, polymorphic: true)
+      #  t.belongs_to(:supplier, foreign_key: true)
       #
-      # See SchemaStatements#add_reference
+      # See 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)
@@ -646,15 +641,12 @@ module ActiveRecord
         @base.rename_column(name, column_name, new_column_name)
       end
 
-      # Adds a reference. Optionally adds a +type+ column, if
-      # <tt>:polymorphic</tt> option is provided.
+      # Adds a reference.
       #
       #  t.references(:user)
-      #  t.references(:user, type: "string")
-      #  t.belongs_to(:supplier, polymorphic: true)
       #  t.belongs_to(:supplier, foreign_key: true)
       #
-      # See SchemaStatements#add_reference
+      # See SchemaStatements#add_reference for details of the options you can use.
       def references(*args)
         options = args.extract_options!
         args.each do |ref_name|
diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
index 9004d86b04..ed19819d63 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
@@ -649,11 +649,21 @@ module ActiveRecord
         indexes(table_name).detect { |i| i.name == index_name }
       end
 
-      # Adds a reference. Optionally adds a +type+ column, if <tt>:polymorphic</tt> option is provided.
-      # The reference column is an +integer+ by default, the <tt>:type</tt> option can be used to specify
-      # a different type.
+      # Adds a reference. The reference column is an integer by default,
+      # the <tt>:type</tt> option can be used to specify a different type.
+      # Optionally adds a +_type+ column, if <tt>:polymorphic</tt> option is provided.
       # <tt>add_reference</tt> and <tt>add_belongs_to</tt> are acceptable.
       #
+      # The +options+ hash can include the following keys:
+      # [<tt>:type</tt>]
+      #   The reference column type. Defaults to +:integer+.
+      # [<tt>:index</tt>]
+      #   Add an appropriate index. Defaults to false.
+      # [<tt>:foreign_key</tt>]
+      #   Add an appropriate foreign key. Defaults to false.
+      # [<tt>:polymorphic</tt>]
+      #   Wether an additional +_type+ column should be added. Defaults to false.
+      #
       # ====== Create a user_id integer column
       #
       #   add_reference(:products, :user)
@@ -662,10 +672,6 @@ module ActiveRecord
       #
       #   add_reference(:products, :user, type: :string)
       #
-      # ====== Create a supplier_id and supplier_type columns
-      #
-      #   add_belongs_to(:products, :supplier, polymorphic: true)
-      #
       # ====== Create supplier_id, supplier_type columns and appropriate index
       #
       #   add_reference(:products, :supplier, polymorphic: true, index: true)