Add more documentation for create_join_table.

Explain that it doesn't create indices by default and
that it also has a block form.

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

@@ -192,6 +192,14 @@ def create_table(table_name, options = {})
       #   Set to true to drop the table before creating it.
       #   Defaults to false.
       #
+      # Note that +create_join_table+ does not create any indices by default; you can use
+      # its block form to do so yourself:
+      #
+      #  create_join_table :products, :categories do |t|
+      #    t.index :products
+      #    t.index :categories
+      #  end
+      #
       # ====== Add a backend specific option to the generated SQL (MySQL)
       #  create_join_table(:assemblies, :parts, options: 'ENGINE=InnoDB DEFAULT CHARSET=utf8')
       # generates:

guides/source/migrations.md

@@ -344,6 +344,16 @@ create_join_table :products, :categories, column_options: {null: true}
 will create the `product_id` and `category_id` with the `:null` option as
 `true`.
 
+`create_join_table` also accepts a block, which you can use to add indices
+(which are not created by default) or additional columns:
+
+```ruby
+create_join_table :products, :categories do |t|
+  t.index :products
+  t.index :categories
+end
+```
+
 ### Changing Tables
 
 A close cousin of `create_table` is `change_table`, used for changing existing