MONGOID-5264 clean up and comment the fields file (#5407)

* MONGOID-5264 clean up and comment the fields filee

* MONGOID-5264 fix tests

Author: neilshweky

lib/mongoid/fields.rb

@@ -538,6 +538,8 @@ def traverse_association_tree(key, &block)
       #   Model.add_defaults(field)
       #
       # @param [ Field ] field The field to add for.
+      #
+      # @api private
       def add_defaults(field)
         default, name = field.default_val, field.name.to_s
         remove_defaults(name)
@@ -557,6 +559,8 @@ def add_defaults(field)
       #
       # @param [ Symbol ] name The name of the field.
       # @param [ Hash ] options The hash of options.
+      #
+      # @api private
       def add_field(name, options = {})
         aliased = options[:as]
         aliased_fields[aliased.to_s] = name if aliased
@@ -584,6 +588,8 @@ def add_field(name, options = {})
       #   # => "called"
       #
       # @param [ Field ] field the field to process
+      #
+      # @api private
       def process_options(field)
         field_options = field.options
 
@@ -606,6 +612,8 @@ def process_options(field)
       # @param [ Symbol ] name The name of the field.
       # @param [ Symbol ] meth The name of the accessor.
       # @param [ Hash ] options The options.
+      #
+      # @api private
       def create_accessors(name, meth, options = {})
         field = fields[name]
 
@@ -629,6 +637,8 @@ def create_accessors(name, meth, options = {})
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
       # @param [ Field ] field The field.
+      #
+      # @api private
       def create_field_getter(name, meth, field)
         generated_methods.module_eval do
           re_define_method(meth) do
@@ -651,6 +661,8 @@ def create_field_getter(name, meth, field)
       #
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
+      #
+      # @api private
       def create_field_getter_before_type_cast(name, meth)
         generated_methods.module_eval do
           re_define_method("#{meth}_before_type_cast") do
@@ -671,6 +683,8 @@ def create_field_getter_before_type_cast(name, meth)
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
       # @param [ Field ] field The field.
+      #
+      # @api private
       def create_field_setter(name, meth, field)
         generated_methods.module_eval do
           re_define_method("#{meth}=") do |value|
@@ -690,6 +704,8 @@ def create_field_setter(name, meth, field)
       #
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
+      #
+      # @api private
       def create_field_check(name, meth)
         generated_methods.module_eval do
           re_define_method("#{meth}?") do
@@ -706,6 +722,8 @@ def create_field_check(name, meth)
       #
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
+      #
+      # @api private
       def create_translations_getter(name, meth)
         generated_methods.module_eval do
           re_define_method("#{meth}_translations") do
@@ -724,6 +742,8 @@ def create_translations_getter(name, meth)
       # @param [ String ] name The name of the attribute.
       # @param [ String ] meth The name of the method.
       # @param [ Field ] field The field.
+      #
+      # @api private
       def create_translations_setter(name, meth, field)
         generated_methods.module_eval do
           re_define_method("#{meth}_translations=") do |value|
@@ -743,6 +763,8 @@ def create_translations_setter(name, meth, field)
       #   Person.generated_methods
       #
       # @return [ Module ] The module of generated methods.
+      #
+      # @api private
       def generated_methods
         @generated_methods ||= begin
           mod = Module.new
@@ -757,38 +779,72 @@ def generated_methods
       #   Model.remove_defaults(name)
       #
       # @param [ String ] name The field name.
+      #
+      # @api private
       def remove_defaults(name)
         pre_processed_defaults.delete_one(name)
         post_processed_defaults.delete_one(name)
       end
 
+      # Create a field for the given name and options.
+      #
+      # @param [ Symbol ] name The name of the field.
+      # @param [ Hash ] options The hash of options.
+      #
+      # @return [ Field ] The created field.
+      #
+      # @api private
       def field_for(name, options)
         opts = options.merge(klass: self)
-        type_mapping = TYPE_MAPPINGS[options[:type]]
-        opts[:type] = type_mapping || unmapped_type(options)
-        if !opts[:type].is_a?(Class)
-          raise Errors::InvalidFieldType.new(self, name, options[:type])
+        opts[:type] = retrieve_and_validate_type(name, options[:type])
+        return Fields::Localized.new(name, opts) if options[:localize]
+        return Fields::ForeignKey.new(name, opts) if options[:identity]
+        Fields::Standard.new(name, opts)
+      end
+
+       # Get the class for the given type.
+       #
+       # @param [ Symbol ] name The name of the field.
+       # @param [ Symbol | Class ] type The type of the field.
+       #
+       # @return [ Class ] The type of the field.
+       #
+       # @raises [ Mongoid::Errors::InvalidFieldType ] if given an invalid field
+       #   type.
+       #
+       # @api private
+       def retrieve_and_validate_type(name, type)
+        type_mapping = TYPE_MAPPINGS[type]
+        result = type_mapping || unmapped_type(type)
+        if !result.is_a?(Class)
+          raise Errors::InvalidFieldType.new(self, name, type)
         else
-          if INVALID_BSON_CLASSES.include?(opts[:type])
-            warn_message = "Using #{opts[:type]} as the field type is not supported. "
-            if opts[:type] == BSON::Decimal128
+          if INVALID_BSON_CLASSES.include?(result)
+            warn_message = "Using #{result} as the field type is not supported. "
+            if result == BSON::Decimal128
               warn_message += "In BSON <= 4, the BSON::Decimal128 type will work as expected for both storing and querying, but will return a BigDecimal on query in BSON 5+."
             else
               warn_message += "Saving values of this type to the database will work as expected, however, querying them will return a value of the native Ruby Integer type."
             end
             Mongoid.logger.warn(warn_message)
           end
         end
-        return Fields::Localized.new(name, opts) if options[:localize]
-        return Fields::ForeignKey.new(name, opts) if options[:identity]
-        Fields::Standard.new(name, opts)
+        result
       end
 
-      def unmapped_type(options)
-        if "Boolean" == options[:type].to_s
+      # Returns the type of the field if the type was not in the TYPE_MAPPINGS
+      # hash.
+      #
+      # @param [ Symbol | Class ] type The type of the field.
+      #
+      # @return [ Class ] The type of the field.
+      #
+      # @api private
+      def unmapped_type(type)
+        if "Boolean" == type.to_s
           Mongoid::Boolean
         else
-          options[:type] || Object
+          type || Object
         end
       end
     end