Add a public API to allow users to specify column types

As a result of all of the refactoring that's been done, it's now
possible for us to define a public API to allow users to specify
behavior. This is an initial implementation so that I can work off of it
in smaller pieces for additional features/refactorings.

The current behavior will continue to stay the same, though I'd like to
refactor towards the automatic schema detection being built off of this
API, and add the ability to opt out of automatic schema detection.

Use cases:

- We can deprecate a lot of the edge cases around types, now that there
  is an alternate path for users who wish to maintain the same behavior.
- I intend to refactor serialized columns to be built on top of this
  API.
- Gem and library maintainers are able to interact with `ActiveRecord`
  at a slightly lower level in a more stable way.
- Interesting ability to reverse the work flow of adding to the schema.
  Model can become the single source of truth for the structure. We can
  compare that to what the database says the schema is, diff them, and
  generate a migration.

11 files changed, 21 insertions, 12 deletions

diff --git a/activerecord/lib/active_record/connection_adapters/type/binary.rb b/activerecord/lib/active_record/connection_adapters/type/binary.rb
index 4b2d1a66e0..60afe44de1 100644
--- a/activerecord/lib/active_record/connection_adapters/type/binary.rb
+++ b/activerecord/lib/active_record/connection_adapters/type/binary.rb
@@ -1,7 +1,7 @@
 module ActiveRecord
   module ConnectionAdapters
     module Type
-      class Binary < Value # :nodoc:
+      class Binary < Value
         def type
           :binary
         end
diff --git a/activerecord/lib/active_record/connection_adapters/type/boolean.rb b/activerecord/lib/active_record/connection_adapters/type/boolean.rb
index 2337bdd563..0d97379189 100644
--- a/activerecord/lib/active_record/connection_adapters/type/boolean.rb
+++ b/activerecord/lib/active_record/connection_adapters/type/boolean.rb
@@ -1,7 +1,7 @@
 module ActiveRecord
   module ConnectionAdapters
     module Type
-      class Boolean < Value # :nodoc:
+      class Boolean < Value
         def type
           :boolean
         end
diff --git a/activerecord/lib/active_record/connection_adapters/type/date.rb b/activerecord/lib/active_record/connection_adapters/type/date.rb
index 1e7205fd0b..e8becbe1f4 100644
--- a/activerecord/lib/active_record/connection_adapters/type/date.rb
+++ b/activerecord/lib/active_record/connection_adapters/type/date.rb
@@ -1,7 +1,7 @@
 module ActiveRecord
   module ConnectionAdapters
     module Type
-      class Date < Value # :nodoc:
+      class Date < Value
         def type
           :date
         end
diff --git a/activerecord/lib/active_record/connection_adapters/type/date_time.rb b/activerecord/lib/active_record/connection_adapters/type/date_time.rb
index c34f4c5a53..64f5d05301 100644
--- a/activerecord/lib/active_record/connection_adapters/type/date_time.rb
+++ b/activerecord/lib/active_record/connection_adapters/type/date_time.rb
@@ -1,7 +1,7 @@
 module ActiveRecord
   module ConnectionAdapters
     module Type
-      class DateTime < Value # :nodoc:
+      class DateTime < Value
         include TimeValue
 
         def type
diff --git a/activerecord/lib/active_record/connection_adapters/type/decimal.rb b/activerecord/lib/active_record/connection_adapters/type/decimal.rb
index ac5af4b963..e93906ba19 100644
--- a/activerecord/lib/active_record/connection_adapters/type/decimal.rb
+++ b/activerecord/lib/active_record/connection_adapters/type/decimal.rb
@@ -1,7 +1,7 @@
 module ActiveRecord
   module ConnectionAdapters
     module Type
-      class Decimal < Value # :nodoc:
+      class Decimal < Value
         include Numeric
 
         def type
diff --git a/activerecord/lib/active_record/connection_adapters/type/float.rb b/activerecord/lib/active_record/connection_adapters/type/float.rb
index 28111e9d8e..f2427d2dfa 100644
--- a/activerecord/lib/active_record/connection_adapters/type/float.rb
+++ b/activerecord/lib/active_record/connection_adapters/type/float.rb
@@ -1,7 +1,7 @@
 module ActiveRecord
   module ConnectionAdapters
     module Type
-      class Float < Value # :nodoc:
+      class Float < Value
         include Numeric
 
         def type
diff --git a/activerecord/lib/active_record/connection_adapters/type/integer.rb b/activerecord/lib/active_record/connection_adapters/type/integer.rb
index 8e6a509b5b..596f4de2a8 100644
--- a/activerecord/lib/active_record/connection_adapters/type/integer.rb
+++ b/activerecord/lib/active_record/connection_adapters/type/integer.rb
@@ -1,7 +1,7 @@
 module ActiveRecord
   module ConnectionAdapters
     module Type
-      class Integer < Value # :nodoc:
+      class Integer < Value
         include Numeric
 
         def type
diff --git a/activerecord/lib/active_record/connection_adapters/type/string.rb b/activerecord/lib/active_record/connection_adapters/type/string.rb
index 55f0e1ee1c..471f949e09 100644
--- a/activerecord/lib/active_record/connection_adapters/type/string.rb
+++ b/activerecord/lib/active_record/connection_adapters/type/string.rb
@@ -1,7 +1,7 @@
 module ActiveRecord
   module ConnectionAdapters
     module Type
-      class String < Value # :nodoc:
+      class String < Value
         def type
           :string
         end
diff --git a/activerecord/lib/active_record/connection_adapters/type/text.rb b/activerecord/lib/active_record/connection_adapters/type/text.rb
index ee5842a3fc..61095ebb38 100644
--- a/activerecord/lib/active_record/connection_adapters/type/text.rb
+++ b/activerecord/lib/active_record/connection_adapters/type/text.rb
@@ -3,7 +3,7 @@ require 'active_record/connection_adapters/type/string'
 module ActiveRecord
   module ConnectionAdapters
     module Type
-      class Text < String # :nodoc:
+      class Text < String
         def type
           :text
         end
diff --git a/activerecord/lib/active_record/connection_adapters/type/time.rb b/activerecord/lib/active_record/connection_adapters/type/time.rb
index 4dd201e3fe..bc331b0fa7 100644
--- a/activerecord/lib/active_record/connection_adapters/type/time.rb
+++ b/activerecord/lib/active_record/connection_adapters/type/time.rb
@@ -1,7 +1,7 @@
 module ActiveRecord
   module ConnectionAdapters
     module Type
-      class Time < Value # :nodoc:
+      class Time < Value
         include TimeValue
 
         def type
diff --git a/activerecord/lib/active_record/connection_adapters/type/value.rb b/activerecord/lib/active_record/connection_adapters/type/value.rb
index 9bbc249c2b..60b443004c 100644
--- a/activerecord/lib/active_record/connection_adapters/type/value.rb
+++ b/activerecord/lib/active_record/connection_adapters/type/value.rb
@@ -1,9 +1,11 @@
 module ActiveRecord
   module ConnectionAdapters
     module Type
-      class Value # :nodoc:
+      class Value
         attr_reader :precision, :scale, :limit
 
+        # Valid options are +precision+, +scale+, and +limit+.
+        # They are only used when dumping schema.
         def initialize(options = {})
           options.assert_valid_keys(:precision, :scale, :limit)
           @precision = options[:precision]
@@ -11,8 +13,13 @@ module ActiveRecord
           @limit = options[:limit]
         end
 
+        # The simplified that this object represents. Subclasses
+        # should override this method.
         def type; end
 
+        # Takes an input from the database, or from attribute setters,
+        # and casts it to a type appropriate for this object. This method
+        # should not be overriden by subclasses. Instead, override `cast_value`.
         def type_cast(value)
           cast_value(value) unless value.nil?
         end
@@ -43,7 +50,9 @@ module ActiveRecord
 
         private
 
-        def cast_value(value)
+        # Responsible for casting values from external sources to the appropriate
+        # type. Called by `type_cast` for all values except `nil`.
+        def cast_value(value) # :api: public
           value
         end
       end