Add docs for the type registry

2 files changed, 24 insertions, 5 deletions

diff --git a/activerecord/lib/active_record/attributes.rb b/activerecord/lib/active_record/attributes.rb
index 45a764bd5a..c8979a60d7 100644
--- a/activerecord/lib/active_record/attributes.rb
+++ b/activerecord/lib/active_record/attributes.rb
@@ -119,15 +119,21 @@ module ActiveRecord
       #     end
       #   end
       #
+      #   # config/initializers/types.rb
+      #   ActiveRecord::Type.register(:money, MoneyType)
+      #
+      #   # /app/models/store_listing.rb
       #   class StoreListing < ActiveRecord::Base
-      #     attribute :price_in_cents, MoneyType.new
+      #     attribute :price_in_cents, :money
       #   end
       #
       #   store_listing = StoreListing.new(price_in_cents: '$10.00')
       #   store_listing.price_in_cents # => 1000
       #
       # For more details on creating custom types, see the documentation for
-      # ActiveRecord::Type::Value.
+      # ActiveRecord::Type::Value. For more details on registering your types
+      # to be referenced by a symbol, see ActiveRecord::Type.register. You can
+      # also pass a type object directly, in place of a symbol.
       #
       # ==== Querying
       #
@@ -152,9 +158,11 @@ module ActiveRecord
       #     end
       #   end
       #
+      #   ActiveRecord::Type.register(:money, MoneyType)
+      #
       #   class Product < ActiveRecord::Base
       #     currency_converter = ConversionRatesFromTheInternet.new
-      #     attribute :price_in_bitcoins, MoneyType.new(currency_converter)
+      #     attribute :price_in_bitcoins, :money, currency_converter
       #   end
       #
       #   Product.where(price_in_bitcoins: Money.new(5, "USD"))
diff --git a/activerecord/lib/active_record/type.rb b/activerecord/lib/active_record/type.rb
index cddd56a20d..2c0cda69d0 100644
--- a/activerecord/lib/active_record/type.rb
+++ b/activerecord/lib/active_record/type.rb
@@ -26,10 +26,21 @@ module ActiveRecord
 
     class << self
       attr_accessor :registry # :nodoc:
+      delegate :add_modifier, to: :registry
 
-      delegate :register, :add_modifier, to: :registry
+      # Add a new type to the registry, allowing it to be referenced as a
+      # symbol by ActiveRecord::Attributes::ClassMethods#attribute.  If your
+      # type is only meant to be used with a specific database adapter, you can
+      # do so by passing +adapter: :postgresql+. If your type has the same
+      # name as a native type for the current adapter, an exception will be
+      # raised unless you specify an +:override+ option. +override: true+ will
+      # cause your type to be used instead of the native type. +override:
+      # false+ will cause the native type to be used over yours if one exists.
+      def register(type_name, klass = nil, **options, &block)
+        registry.register(type_name, klass, **options, &block)
+      end
 
-      def lookup(*args, adapter: current_adapter_name, **kwargs)
+      def lookup(*args, adapter: current_adapter_name, **kwargs) # :nodoc:
         registry.lookup(*args, adapter: adapter, **kwargs)
       end