1 files changed, 26 insertions, 15 deletions
diff --git a/guides/source/active_record_migrations.md b/guides/source/active_record_migrations.md
index bd7dbd0f11..d91c9bd606 100644
--- a/guides/source/active_record_migrations.md
+++ b/guides/source/active_record_migrations.md
@@ -41,7 +41,7 @@ class CreateProducts < ActiveRecord::Migration[5.0]
       t.string :name
       t.text :description
 
-      t.timestamps null: false
+      t.timestamps
     end
   end
 end
@@ -241,12 +241,13 @@ generates
 ```ruby
 class AddUserRefToProducts < ActiveRecord::Migration[5.0]
   def change
-    add_reference :products, :user, index: true, foreign_key: true
+    add_reference :products, :user, foreign_key: true
   end
 end
 ```
 
 This migration will create a `user_id` column and appropriate index.
+For more `add_reference` options, visit the [API documentation](http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-add_reference).
 
 There is also a generator which will produce join tables if `JoinTable` is part of the name:
 
@@ -287,7 +288,7 @@ class CreateProducts < ActiveRecord::Migration[5.0]
       t.string :name
       t.text :description
 
-      t.timestamps null: false
+      t.timestamps
     end
   end
 end
@@ -312,7 +313,7 @@ will produce a migration that looks like this
 class AddDetailsToProducts < ActiveRecord::Migration[5.0]
   def change
     add_column :products, :price, :decimal, precision: 5, scale: 2
-    add_reference :products, :supplier, polymorphic: true, index: true
+    add_reference :products, :supplier, polymorphic: true
   end
 end
 ```
@@ -353,7 +354,14 @@ end
 ```
 
 will append `ENGINE=BLACKHOLE` to the SQL statement used to create the table
-(when using MySQL, the default is `ENGINE=InnoDB`).
+(when using MySQL or MariaDB, the default is `ENGINE=InnoDB`).
+
+Also you can pass the `:comment` option with any description for the table
+that will be stored in database itself and can be viewed with database administration
+tools, such as MySQL Workbench or PgAdmin III. It's highly recommended to specify
+comments in migrations for applications with large databases as it helps people
+to understand data model and generate documentation.
+Currently only the MySQL and PostgreSQL adapters support comments.
 
 ### Creating a Join Table
 
@@ -454,10 +462,13 @@ number of digits after the decimal point.
 are using a dynamic value (such as a date), the default will only be calculated
 the first time (i.e. on the date the migration is applied).
 * `index`        Adds an index for the column.
+* `comment`      Adds a comment for the column.
 
 Some adapters may support additional options; see the adapter specific API docs
 for further information.
 
+NOTE: `null` and `default` cannot be specified via command line.
+
 ### Foreign Keys
 
 While it's not required you might want to add foreign key constraints to
@@ -847,7 +858,7 @@ class CreateProducts < ActiveRecord::Migration[5.0]
       create_table :products do |t|
         t.string :name
         t.text :description
-        t.timestamps null: false
+        t.timestamps
       end
     end
 
@@ -970,7 +981,7 @@ this, then you should set the schema format to `:sql`.
 Instead of using Active Record's schema dumper, the database's structure will
 be dumped using a tool specific to the database (via the `db:structure:dump`
 rails task) into `db/structure.sql`. For example, for PostgreSQL, the `pg_dump`
-utility is used. For MySQL, this file will contain the output of
+utility is used. For MySQL and MariaDB, this file will contain the output of
 `SHOW CREATE TABLE` for the various tables.
 
 Loading these schemas is simply a question of executing the SQL statements they
@@ -1009,10 +1020,10 @@ such features, the `execute` method can be used to execute arbitrary SQL.
 Migrations and Seed Data
 ------------------------
 
-The main purpose of Rails' migration feature is to issue commands that modify the 
-schema using a consistent process. Migrations can also be used 
-to add or modify data. This is useful in an existing database that can't be destroyed 
-and recreated, such as a production database. 
+The main purpose of Rails' migration feature is to issue commands that modify the
+schema using a consistent process. Migrations can also be used
+to add or modify data. This is useful in an existing database that can't be destroyed
+and recreated, such as a production database.
 
 ```ruby
 class AddInitialProducts < ActiveRecord::Migration[5.0]
@@ -1028,10 +1039,10 @@ class AddInitialProducts < ActiveRecord::Migration[5.0]
 end
 ```
 
-To add initial data after a database is created, Rails has a built-in 
-'seeds' feature that makes the process quick and easy. This is especially 
-useful when reloading the database frequently in development and test environments. 
-It's easy to get started with this feature: just fill up `db/seeds.rb` with some 
+To add initial data after a database is created, Rails has a built-in
+'seeds' feature that makes the process quick and easy. This is especially
+useful when reloading the database frequently in development and test environments.
+It's easy to get started with this feature: just fill up `db/seeds.rb` with some
 Ruby code, and run `rails db:seed`:
 
 ```ruby