synchronize code and docs for `timestamps` and `add_timestamps`.

This makes the following changes:
  * warn if `:null` is not passed to `add_timestamps`
  * `timestamps` method docs link to `add_timestamps` docs
  * explain where additional options go
  * adjust examples to include `null: false` (to prevent deprecation warnings)

3 files changed, 11 insertions, 2 deletions

diff --git a/activerecord/test/cases/adapters/mysql/active_schema_test.rb b/activerecord/test/cases/adapters/mysql/active_schema_test.rb
index a84673e452..413f67da26 100644
--- a/activerecord/test/cases/adapters/mysql/active_schema_test.rb
+++ b/activerecord/test/cases/adapters/mysql/active_schema_test.rb
@@ -92,7 +92,7 @@ class ActiveSchemaTest < ActiveRecord::TestCase
     with_real_execute do
       begin
         ActiveRecord::Base.connection.create_table :delete_me
-        ActiveRecord::Base.connection.add_timestamps :delete_me
+        ActiveRecord::Base.connection.add_timestamps :delete_me, null: true
         assert column_present?('delete_me', 'updated_at', 'datetime')
         assert column_present?('delete_me', 'created_at', 'datetime')
       ensure
diff --git a/activerecord/test/cases/adapters/mysql2/active_schema_test.rb b/activerecord/test/cases/adapters/mysql2/active_schema_test.rb
index 49cfafd7a5..3d97182356 100644
--- a/activerecord/test/cases/adapters/mysql2/active_schema_test.rb
+++ b/activerecord/test/cases/adapters/mysql2/active_schema_test.rb
@@ -92,7 +92,7 @@ class ActiveSchemaTest < ActiveRecord::TestCase
     with_real_execute do
       begin
         ActiveRecord::Base.connection.create_table :delete_me
-        ActiveRecord::Base.connection.add_timestamps :delete_me
+        ActiveRecord::Base.connection.add_timestamps :delete_me, null: true
         assert column_present?('delete_me', 'updated_at', 'datetime')
         assert column_present?('delete_me', 'created_at', 'datetime')
       ensure
diff --git a/activerecord/test/cases/ar_schema_test.rb b/activerecord/test/cases/ar_schema_test.rb
index b6333240a8..025c9fe6f9 100644
--- a/activerecord/test/cases/ar_schema_test.rb
+++ b/activerecord/test/cases/ar_schema_test.rb
@@ -115,6 +115,15 @@ if ActiveRecord::Base.connection.supports_migrations?
       end
     end
 
+    def test_timestamps_without_null_is_deprecated_on_add_timestamps
+      assert_deprecated do
+        ActiveRecord::Schema.define do
+          create_table :has_timestamps
+          add_timestamps :has_timestamps
+        end
+      end
+    end
+
     def test_no_deprecation_warning_from_timestamps_on_create_table
       assert_not_deprecated do
         ActiveRecord::Schema.define do