Merge pull request #35105 from olivierlacan/document-table-foreign-key

Hint at advanced options for foreign_key

activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb

@@ -682,9 +682,10 @@ def remove_references(*args, **options)
       end
       alias :remove_belongs_to :remove_references
 
-      # Adds a foreign key.
+      # Adds a foreign key to the table using a supplied table name.
       #
       #  t.foreign_key(:authors)
+      #  t.foreign_key(:authors, column: :author_id, primary_key: "id")
       #
       # See {connection.add_foreign_key}[rdoc-ref:SchemaStatements#add_foreign_key]
       def foreign_key(*args)