MONGOID-5222 add note to custom types section

Author: neilshweky

docs/reference/fields.txt

@@ -1007,6 +1007,14 @@ setter methods for fields of your custom type.
    venue = Venue.new(location: point) # This uses the Point#mongoize instance method.
    venue = Venue.new(location: [ 12, 24 ]) # This uses the Point.mongoize class method.
 
+.. note::
+
+  The ``mongoize`` method should raise an "InvalidValue" error on values that
+  are uncastable to your custom type. Mongoid will handle catching that error
+  and writing ``nil`` if the ``validate_attribute_types`` flag is turned off.
+  See the secion on :ref:`Uncastable Values <uncastable-values>` for more
+  details.
+
 The class method ``demongoize`` does the inverse of ``mongoize``. It takes the raw object
 from the MongoDB Ruby driver and converts it to an instance of your custom type.
 In this case, the database driver returns an ``Array`` and we instantiate a ``Point`` from it.