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)

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

@@ -226,7 +226,7 @@ module ActiveRecord
       #     t.integer :shop_id, :creator_id
       #     t.string  :item_number, index: true
       #     t.string  :name, :value, default: "Untitled"
-      #     t.timestamps
+      #     t.timestamps null: false
       #   end
       #
       # There's a short-hand method for each of the type values declared at the top. And then there's
@@ -287,7 +287,9 @@ module ActiveRecord
       end
 
       # Appends <tt>:datetime</tt> columns <tt>:created_at</tt> and
-      # <tt>:updated_at</tt> to the table.
+      # <tt>:updated_at</tt> to the table. See SchemaStatements#add_timestamps
+      #
+      #   t.timestamps null: false
       def timestamps(*args)
         options = args.extract_options!
         emit_warning_if_null_unspecified(options)
@@ -412,8 +414,6 @@ module ActiveRecord
     #   end
     #
     class Table
-      include TimestampDefaultDeprecation
-
       attr_reader :name
 
       def initialize(table_name, base)
@@ -462,9 +462,8 @@ module ActiveRecord
 
       # Adds timestamps (+created_at+ and +updated_at+) columns to the table. See SchemaStatements#add_timestamps
       #
-      #  t.timestamps
+      #  t.timestamps null: false
       def timestamps(options = {})
-        emit_warning_if_null_unspecified(options)
         @base.add_timestamps(name, options)
       end
 

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

@@ -835,11 +835,14 @@ module ActiveRecord
         columns
       end
 
-      # Adds timestamps (+created_at+ and +updated_at+) columns to the named table.
+      include TimestampDefaultDeprecation
+      # Adds timestamps (+created_at+ and +updated_at+) columns to +table_name+.
+      # Additional options (like <tt>null: false</tt>) are forwarded to #add_column.
       #
-      #   add_timestamps(:suppliers)
+      #   add_timestamps(:suppliers, null: false)
       #
       def add_timestamps(table_name, options = {})
+        emit_warning_if_null_unspecified(options)
         add_column table_name, :created_at, :datetime, options
         add_column table_name, :updated_at, :datetime, options
       end

activerecord/lib/active_record/connection_adapters/abstract_adapter.rb

@@ -24,6 +24,7 @@ module ActiveRecord
       autoload :TableDefinition
       autoload :Table
       autoload :AlterTable
+      autoload :TimestampDefaultDeprecation
     end
 
     autoload_at 'active_record/connection_adapters/abstract/connection_pool' do

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

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

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