Requested changes

Author: johnnyshields

docs/reference/fields.txt

@@ -897,14 +897,14 @@ can use in our model class as follows:
     field :location, type: Point
   end
 
-You may optionally declare a symbol mapping for the new field type in an initializer:
+You may optionally declare a mapping for the new field type in an initializer:
 
 .. code-block:: ruby
 
   # in /config/initializers/mongoid_custom_fields.rb
 
   Mongoid::Fields.configure do
-    type :point, Point
+    define_type :point, Point
   end
 
 

docs/release-notes/mongoid-8.0.txt

@@ -313,7 +313,7 @@ Mongoid 8.0 adds the ability to define custom ``field :type`` Symbol values as f
   # in /config/initializers/mongoid_custom_fields.rb
 
   Mongoid::Fields.configure do
-    type :point, Point
+    define_type :point, Point
   end
 
 Refer to the :ref:`docs <http://docs.mongodb.org/manual/reference/fields/#custom-field-types>` for details.

lib/config/locales/en.yml

@@ -176,8 +176,8 @@ en:
             Refer to:
             https://docs.mongodb.com/mongoid/current/reference/fields/#custom-field-options"
         invalid_field_type:
-          message: "Invalid field type %{type_inspection} for field :%{field} on model '%{klass}'."
-          summary: "Model '%{klass}' defines a field :%{field} with an unknown :type value
+          message: "Invalid field type %{type_inspection} for field '%{field}' on model '%{klass}'."
+          summary: "Model '%{klass}' defines a field '%{field}' with an unknown :type value
             %{type_inspection}. This value is neither present in Mongoid's default type mapping,
             nor defined in a custom field type mapping."
           resolution: "Please provide a valid :type value for the field. If you

lib/mongoid/fields.rb

@@ -240,7 +240,11 @@ def configure(&block)
       #   Mongoid::Fields.configure do
       #     type :point, Point
       #   end
-      def type(symbol, klass)
+      #
+      # @param [ Symbol ] symbol the symbol identifier of the defined type
+      # @param [ Class ] klass the class of the defined type, which must
+      #   include mongoize and related methods.
+      def define_type(symbol, klass)
         Fields::FieldTypes.define(symbol, klass)
       end
 

lib/mongoid/fields/field_types.rb

@@ -3,12 +3,13 @@
 module Mongoid
   module Fields
 
-    # Singleton module which contains a cache for field type definitions.
+    # Singleton module which contains a mapping of field types to field class.
     # Custom field types can be configured.
     module FieldTypes
-      extend self
 
-      # For fields defined with symbols use the correct class.
+      # The default mapping of field type symbol to class.
+      #
+      # @api private
       DEFAULT_MAPPING = {
         array: Array,
         bigdecimal: BigDecimal,
@@ -35,32 +36,55 @@ module FieldTypes
         time_with_zone: ActiveSupport::TimeWithZone
       }.with_indifferent_access.freeze
 
-      def get(value)
-        value = value.to_sym if value.is_a?(String)
-        mapping[value] || handle_unmapped_type(value)
-      end
+      class << self
 
-      def define(symbol, klass)
-        mapping[symbol.to_sym] = klass
-      end
+        # Gets a field class given its mapping identifier.
+        #
+        # @example
+        #   Mongoid::FieldTypes.get(:point)
+        #
+        # @param [ Symbol | String ] value the identifier of the defined type
+        def get(value)
+          mapping[value] || handle_unmapped_type(value)
+        end
 
-      delegate :delete, to: :mapping
+        # Defines a field type mapping, for later use in field :type option.
+        #
+        # @example
+        #   Mongoid::FieldTypes.define(:point, Point)
+        #
+        # @param [ Symbol ] symbol the symbol identifier of the defined type
+        # @param [ Class ] klass the class of the defined type, which must
+        #   include mongoize and related methods.
+        def define(symbol, klass)
+          mapping[symbol.to_sym] = klass
+        end
 
-      private
+        delegate :delete, to: :mapping
 
-      def mapping
-        @mapping ||= DEFAULT_MAPPING.dup
-      end
+        private
 
-      def handle_unmapped_type(type)
-        return Object if type.nil?
-
-        if type.is_a?(Module)
-          return Mongoid::Boolean if type.to_s == 'Boolean'
-          return type
+        # The memoized mapping of field type definitions to classes.
+        #
+        # @return [ ActiveSupport::HashWithIndifferentAccess<Symbol, Class> ] The memoized field mapping.
+        def mapping
+          @mapping ||= DEFAULT_MAPPING.dup
         end
 
-        nil
+        # Handles fallback for case where mapping does not contain the
+        # requested type.
+        #
+        # @return [ Class | nil ] The class to use as a fallback, or nil.
+        def handle_unmapped_type(type)
+          return Object if type.nil?
+
+          if type.is_a?(Module)
+            return Mongoid::Boolean if type.to_s == 'Boolean'
+            return type
+          end
+
+          nil
+        end
       end
     end
   end

spec/mongoid/errors/invalid_field_type_spec.rb

@@ -17,13 +17,13 @@
 
       it "contains the problem in the message" do
         expect(error.message).to include(
-          "Invalid field type :stringgy for field :first_name on model 'Person'."
+          "Invalid field type :stringgy for field 'first_name' on model 'Person'."
         )
       end
 
       it "contains the summary in the message" do
         expect(error.message).to include(
-          "Model 'Person' defines a field :first_name with an unknown :type value :stringgy."
+          "Model 'Person' defines a field 'first_name' with an unknown :type value :stringgy."
         )
       end
     end
@@ -35,13 +35,13 @@
 
       it "contains the problem in the message" do
         expect(error.message).to include(
-          %q,Invalid field type "stringgy" for field :first_name on model 'Person'.,
+          %q,Invalid field type "stringgy" for field 'first_name' on model 'Person'.,
         )
       end
 
       it "contains the summary in the message" do
         expect(error.message).to include(
-          %q,Model 'Person' defines a field :first_name with an unknown :type value "stringgy".,
+          %q,Model 'Person' defines a field 'first_name' with an unknown :type value "stringgy".,
         )
       end
     end