MONGOID-5222 add documentation

Author: neilshweky

docs/reference/configuration.txt

@@ -434,6 +434,11 @@ for details on driver options.
       # (default: false)
       use_utc: false
 
+      # Raise an error on the assignment of a value that cannot be casted to
+      # the assigning field type. If this flag is off, no error will be raised
+      # and nil will be written.
+      validate_attribute_types: true
+
       # (Deprecated) In MongoDB 4.0 and earlier, set whether to create
       # indexes in the background by default. (default: false)
       background_indexing: false

docs/reference/fields.txt

@@ -827,6 +827,35 @@ Mongoid also defines the ``id`` field aliased to ``_id``. The ``id``
 alias can :ref:`be removed <unalias-id>` if desired (such as to integrate
 with systems that use the ``id`` field to store value different from ``_id``.
 
+.. _uncastable-values:
+
+Assigning Uncastable Values
+---------------------------
+
+In Mongoid 8, Mongoid has standardized the treatment of the assignment of
+"uncastable" values. A value is considered "uncastable" when it cannot be
+coerced to the type of the assigning field. For example:
+
+.. code::
+
+  class User
+    include Mongoid::Document
+
+    field :name, type: Integer
+  end
+
+  User.new(name: [ "hello" ])
+
+Assigning an array to a field of type Integer doesn't work since an array can't
+be coerced to an Integer. To deal with this case, Mongoid has introduced the
+``validate_attribute_types`` flag.
+
+When the ``validate_attribute_types`` flag is turned on, the assignment of uncastable
+values to a field will cause an ``InvalidValue`` error to be raised.
+
+When the ``validate_attribute_types`` flag is turned off, the assignment of uncastable
+values to a field will cause a ``nil`` to be written.
+
 
 .. _customizing-field-behavior:
 

docs/release-notes/mongoid-8.0.txt

@@ -57,6 +57,40 @@ changed in Mongoid 8.0:
 Please refer to :ref:`configuration option <configuration-options>` for
 the description and effects of each of these options.
 
+Storing Uncastable Types and the ``validate_attribute_types`` Flag
+------------------------------------------------------------------
+
+In Mongoid 8, Mongoid deals with "uncastable values" based on the values of the
+``validates_attribute_types`` flag. If the ``validates_attribute_types`` flag
+is set to true, an ``InvalidValue`` error is raise, and if it is set to false
+a ``nil`` is written. See the secion on :ref:`Uncastable Values <uncastable-values>`
+for more details.
+
+Some ``mongoize`` methods were also changed to perform consistently with rails
+and the other mongoize methods. The following is a table of the changes in
+functionality:
+
++--------------+------------------------+------------------------+-------------------+
+| Field Type   | Situation              | Previous Functionality | New Functionality |
++==============+========================+========================+===================+
+| Integer/Float| When a non-numeric     | return ``nil``         | return ``42``     |
+|              | string starts with a   |                        |                   |
+|              | number: "42bogus"      |                        |                   |
++--------------+------------------------+------------------------+-------------------+
+| Boolean      | When a non-boolean     | return ``false``       | return ``nil`` or |
+|              | string is assigned:    |                        | raise             |
+|              | "bogus value"          |                        | ``InvalidError``  |
++--------------+------------------------+------------------------+-------------------+
+| Symbol       | When a value that does | return ``nil``         | return ``nil`` or |
+|              | not respond to         |                        | raise             |
+|              | ``to_sym`` is          |                        | ``InvalidError``  |
+|              | assigned: ``[]``       |                        |                   |
++--------------+------------------------+------------------------+-------------------+
+| All Other    | When an uncastable     | undefined behavior,    | return ``nil`` or |
+| Types        | value is assigned      | occasionally raises    | raise             |
+|              |                        | ``NoMethodError``      | ``InvalidError``  |
++--------------+------------------------+------------------------+-------------------+
+
 
 Order of Callback Invocation
 ----------------------------