mongoid 7.5.0 → 8.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32597c6d6b536f273850be1989db0d876026d2bffda067d7923f173c3966faa6
-  data.tar.gz: 97fffa62c90ae5c20e7dcf00eb151b557c26ab5ae676c45b5651efa5143cf34c
+  metadata.gz: 9c2c1f57188d73b1d7f6d965b01a05cd97ddab316855221e6b23f70858e820af
+  data.tar.gz: 0ad8309b683b8031796d3e3d99c36840481b7b2cc8aa773e32c4d1b050380671
 SHA512:
-  metadata.gz: dbe0c003a7e058f5ab6ac5592170ef1a26e02bf9be729b889c55a3a70af4e0c8b6e52f7157cc9b40879545689972769bae5deabf6814ce1ebeb97fdf1a128212
-  data.tar.gz: d696cd95560d51b34318e7f25467450dde8461383dd17830f1177363cbf006c863b1268a2b79616e563343a3fd0e388c9d3bde67821b698b4cf0035bbfc9b719
+  metadata.gz: 00ca56917eafe55f9b4ef394569ac8a64023c67906fdd65522d74a95046a7cacab42ca11baea2917e80f803cadc9c7d484e170227fcdf48a14a8656e96639fdb
+  data.tar.gz: 159b5215f615ca52777a81127e8312767d4e66adbb77e047d01769ed90281ef4959de4bda42e5ce2eadd9803e4a3d11f5d3d50c8da467241f3dd16bd90f69226

data/README.md

@@ -19,9 +19,9 @@ Compatibility
 
 Mongoid supports and is tested against:
 
-- MRI 2.5 - 3.1
-- JRuby 9.2
-- MongoDB server 2.6 - 6.0
+- MRI 2.6 - 3.1
+- JRuby 9.3
+- MongoDB server 3.6 - 6.0
 
 Issues
 ------

data/lib/config/locales/en.yml

@@ -1,4 +1,8 @@
 en:
+  errors:
+    messages:
+      taken: "has already been taken"
+
   mongoid:
     errors:
       messages:
@@ -61,7 +65,7 @@ en:
             and the following ids were not found: %{missing}."
           resolution: "Search for an id that is in the database or set
             the Mongoid.raise_not_found_error configuration option to false,
-            which will cause a nil to be returned instead of raising this error when
+            which will cause nil to be returned instead of raising this error when
             searching for a single id, or only the matched documents when searching
             for multiples."
         document_with_attributes_not_found:
@@ -71,15 +75,17 @@ en:
             will be raised."
           resolution: "Search for attributes that are in the database or set
             the Mongoid.raise_not_found_error configuration option to false,
-            which will cause a nil to be returned instead of raising this error."
-        eager_load:
-          message: "Eager loading :%{name} is not supported since it is a
-            polymorphic belongs_to association."
-          summary: "Mongoid cannot currently determine the classes it needs to
-            eager load when the association is polymorphic. The parents reside in
-            different collections so a simple id lookup is not sufficient enough."
-          resolution: "Don't attempt to perform this action and have patience,
-            maybe this will be supported in the future."
+            which will cause nil to be returned instead of raising this error."
+        document_with_shard_key_not_found:
+          message: "Document not found for class %{klass} with id %{missing} and
+            shard key %{shard_key}."
+          summary: "When calling %{klass}.find with an id and a shard key, each
+            parameter must match a document in the database or this error will
+            be raised. The search was for the id: %{missing} with
+            shard_key: %{shard_key} and it was not found."
+          resolution: "Search for an id/shard key that is in the database or set
+            the Mongoid.raise_not_found_error configuration option to false,
+            which will cause nil to be returned instead of raising this error."
         empty_config_file:
           message: "Empty configuration file: %{path}."
           summary: "Your mongoid.yml configuration file appears to be empty."
@@ -126,6 +132,17 @@ en:
             allowed."
           resolution: "Try setting the discriminator key on %{superclass} or one of %{class_name}'s
             ancestors."
+        invalid_dot_dollar_assignment:
+          message: "Cannot set the %{attr} attribute on the %{klass} class."
+          summary: "Calling the setters for fields that start with a dollar
+            sign ($) or contain a dot/period (.) is prohibited. See the
+            Mongoid documentation on Field Names with Dots/Periods (.) and
+            Dollar Signs ($) for more information."
+          resolution: "In order to set fields that start with a dollar
+            sign ($) or contain a dot/period (.), the aggregation pipeline can
+            be used. MongoDB provides specific operators for working with these
+            fields. Refer to the MongoDB documentation here:
+            https://www.mongodb.com/docs/manual/core/dot-dollar-considerations/"
         invalid_elem_match_operator:
           message: "Invalid $elemMatch operator '%{operator}'."
           summary: "You misspelled an operator or are using an operator that
@@ -146,7 +163,7 @@ en:
           resolution: "Valid expression operators are: %{valid_operators}.
             Ensure you are using one of these operators."
         invalid_field:
-          message: "Defining a field named '%{name}' is not allowed."
+          message: "Defining a field named '%{field}' is not allowed."
           summary: "Defining this field would override the method '%{name}',
             which would cause issues with expectations around the original
             method and cause extremely hard to debug issues. The original
@@ -181,6 +198,13 @@ en:
             \_\_end\n\n
             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
+            %{type_inspection}."
+          resolution: "Please provide a valid type value for the field.
+            Refer to:
+            https://docs.mongodb.com/mongoid/current/reference/fields/#using-symbols-or-strings-instead-of-classes"
         invalid_includes:
           message: "Invalid includes directive: %{klass}.includes(%{args})"
           summary: "Eager loading in Mongoid only supports providing arguments
@@ -196,7 +220,6 @@ en:
             Valid options are:\n
             \_\_background: true|false\n
             \_\_database: 'database_name'\n
-            \_\_drop_dups: true|false\n
             \_\_name: 'index_name'\n
             \_\_sparse: true|false\n
             \_\_unique: true|false\n
@@ -215,7 +238,8 @@ en:
             \_\_language_override\n
             \_\_default_language\n
             \_\_collation\n
-            Valid types are: 1, -1, '2d', '2dsphere', 'geoHaystack', 'text', 'hashed'\n\n
+            \_\_wildcard_projection: { 'path.to.field.a': 1, 'path.to.field.b': 0 }\n
+            Valid types are: 1, -1, '2d', '2dsphere', 'geoHaystack (deprecated)', 'text', 'hashed'\n\n
             Example:\n
             \_\_class Band\n
             \_\_\_\_include Mongoid::Document\n
@@ -349,10 +373,6 @@ en:
             from the child side which association to go in."
           resolution: "Set the values from the parent, or redefine the association
             with only a single definition in the parent."
-        invalid_value:
-          message: "Value of type %{value_class} cannot be written to a field of type %{field_class}"
-          summary: "Tried to set a value of type %{value_class} to a field of type %{field_class}"
-          resolution: "Verify if the value to be set correspond to field definition"
         mixed_relations:
           message: "Referencing a(n) %{embedded} document from the %{root}
             document via a non-embedded association is not allowed since the
@@ -409,19 +429,18 @@ en:
           summary: "Mongoid attempted to find a document of the class %{klass}
             but none exist."
           resolution: "Create a document of class %{klass} or use a finder
-            method that returns nil when no documents are found instead of
-            raising an exception."
+            method that does not raise an exception when no documents are
+            found."
         no_environment:
           message: "Could not load the configuration since no environment
             was defined."
-          summary: "Mongoid attempted to find the appropriate environment
-            but no Rails.env, Sinatra::Base.environment, RACK_ENV, or
-            MONGOID_ENV could be found."
-          resolution: "Make sure some environment is set from the mentioned
-            options. Mongoid cannot load configuration from the yaml without
-            knowing which environment it is in, and we have considered
-            defaulting to development an undesirable side effect of this not
-            being defined."
+          summary: "Mongoid could not determine the environment to use because
+            it was not specified in any of the following locations:
+            Rails.env, Sinatra::Base.environment,
+            ENV[\"RACK_ENV\"], ENV[\"MONGOID_ENV\"]. Without knowing the
+            environment, Mongoid cannot load its configuration."
+          resolution: "Please ensure an environment is set in one of the
+            listed locations. The environment must be explicitly set."
         no_map_reduce_output:
           message: "No output location was specified for the map/reduce
             operation."
@@ -548,11 +567,9 @@ en:
             server versions 3.6 and higher."
           resolution: "Verify that all servers in your deployment are at least
             version 3.6 or don't attempt to use sessions with older server versions."
-        taken:
-          "is already taken"
         too_many_nested_attribute_records:
           message: "Accepting nested attributes for %{association} is limited
-            to %{limit} records."
+            to %{limit} documents."
           summary: "More documents were sent to be processed than the allowed
             limit."
           resolution: "The limit is set as an option to the macro, for example:

data/lib/mongoid/association/accessors.rb

@@ -15,8 +15,8 @@ module Mongoid
       # @example Build the association.
       #   person.__build__(:addresses, { :_id => 1 }, association)
       #
-      # @param [ String, Symbol ] name The name of the association.
-      # @param [ Hash, BSON::ObjectId ] object The id or attributes to use.
+      # @param [ String | Symbol ] name The name of the association.
+      # @param [ Hash | BSON::ObjectId ] object The id or attributes to use.
       # @param [ Association ] association The association metadata.
       # @param [ Hash ] selected_fields Fields which were retrieved via #only.
       #   If selected_fields is specified, fields not listed in it will not be
@@ -33,7 +33,7 @@ module Mongoid
       # @example Create the association.
       #   person.create_relation(document, association)
       #
-      # @param [ Document, Array<Document> ] object The association target.
+      # @param [ Document | Array<Document> ] object The association target.
       # @param [ Association ] association The association metadata.
       # @param [ Hash ] selected_fields Fields which were retrieved via #only.
       #   If selected_fields is specified, fields not listed in it will not be
@@ -42,8 +42,23 @@ module Mongoid
       # @return [ Proxy ] The association.
       def create_relation(object, association, selected_fields = nil)
         type = @attributes[association.inverse_type]
-        target = association.build(self, object, type, selected_fields)
-        target ? association.create_relation(self, target) : nil
+        target = if t = association.build(self, object, type, selected_fields)
+          association.create_relation(self, t)
+        else
+          nil
+        end
+
+        # Only need to do this on embedded associations. The pending callbacks
+        # are only added when materializing the documents, which only happens
+        # on embedded associations. There is no call to the database in the
+        # construction of a referenced association.
+        if association.embedded?
+          Array(target).each do |doc|
+            doc.try(:run_pending_callbacks)
+          end
+        end
+
+        target
       end
 
       # Resets the criteria inside the association proxy. Used by many-to-many
@@ -65,7 +80,7 @@ module Mongoid
       # @example Set the proxy on the document.
       #   person.set(:addresses, addresses)
       #
-      # @param [ String, Symbol ] name The name of the association.
+      # @param [ String | Symbol ] name The name of the association.
       # @param [ Proxy ] relation The association to set.
       #
       # @return [ Proxy ] The association.
@@ -86,10 +101,23 @@ module Mongoid
       # @param [ Symbol ] name The name of the association.
       # @param [ Association ] association The association metadata.
       # @param [ Object ] object The object used to build the association.
-      # @param [ true, false ] reload If the association is to be reloaded.
+      # @param [ true | false ] reload If the association is to be reloaded.
       #
       # @return [ Proxy ] The association.
       def get_relation(name, association, object, reload = false)
+        field_name = database_field_name(name)
+
+        # As per the comments under MONGOID-5034, I've decided to only raise on
+        # embedded associations for a missing attribute. Rails does not raise
+        # for a missing attribute on referenced associations.
+        # We also don't want to raise if we're retrieving an association within
+        # the codebase. This is often done when retrieving the inverse association
+        # during binding or when cascading callbacks. Whenever we retrieve
+        # associations within the codebase, we use without_autobuild.
+        if !without_autobuild? && association.embedded? && attribute_missing?(field_name)
+          raise ActiveModel::MissingAttributeError, "Missing attribute: '#{field_name}'"
+        end
+
         if !reload && (value = ivar(name)) != false
           value
         else
@@ -197,7 +225,7 @@ module Mongoid
       # @example Is autobuild disabled?
       #   document.without_autobuild?
       #
-      # @return [ true, false ] If autobuild is disabled.
+      # @return [ true | false ] If autobuild is disabled.
       def without_autobuild?
         Threaded.executing?(:without_autobuild)
       end
@@ -291,7 +319,7 @@ module Mongoid
         ids_method = "#{association.name.to_s.singularize}_ids"
         association.inverse_class.tap do |klass|
           klass.re_define_method(ids_method) do
-            send(association.name).only(:_id).map(&:_id)
+            send(association.name).pluck(:_id)
           end
         end
       end
@@ -341,6 +369,7 @@ module Mongoid
       #  @return [ Class ] The class being set up.
       def self.define_ids_setter!(association)
         ids_method = "#{association.name.to_s.singularize}_ids="
+        association.inverse_class.aliased_associations[ids_method.chop] = association.name.to_s
         association.inverse_class.tap do |klass|
           klass.re_define_method(ids_method) do |ids|
             send(association.setter, association.relation_class.find(ids.reject(&:blank?)))

data/lib/mongoid/association/bindable.rb

@@ -15,7 +15,7 @@ module Mongoid
       #   Binding.new(base, target, association)
       #
       # @param [ Document ] base The base of the binding.
-      # @param [ Document, Array<Document> ] target The target of the binding.
+      # @param [ Document | Array<Document> ] target The target of the binding.
       # @param [ Association ] association The association metadata.
       def initialize(base, target, association)
         @_base, @_target, @_association = base, target, association
@@ -60,6 +60,53 @@ module Mongoid
         end
       end
 
+      # Remove the associated document from the inverse's association.
+      #
+      # @param [ Document ] doc The document to remove.
+      def remove_associated(doc)
+        if inverse = _association.inverse(doc)
+          if _association.many?
+            remove_associated_many(doc, inverse)
+          elsif _association.in_to?
+            remove_associated_in_to(doc, inverse)
+          end
+        end
+      end
+
+      # Remove the associated document from the inverse's association.
+      #
+      # This method removes the associated on *_many relationships.
+      #
+      # @param [ Document ] doc The document to remove.
+      # @param [ Symbol ] inverse The name of the inverse.
+      def remove_associated_many(doc, inverse)
+        # We only want to remove the inverse association when the inverse
+        # document is in memory.
+        if inv = doc.ivar(inverse)
+          # This first condition is needed because when assigning the
+          # embeds_many association using the same embeds_many
+          # association, we delete from the array we are about to assign.
+          if _base != inv && (associated = inv.ivar(_association.name))
+            associated.delete(doc)
+          end
+        end
+      end
+
+      # Remove the associated document from the inverse's association.
+      #
+      # This method removes associated on belongs_to and embedded_in
+      # associations.
+      #
+      # @param [ Document ] doc The document to remove.
+      # @param [ Symbol ] inverse The name of the inverse.
+      def remove_associated_in_to(doc, inverse)
+        # We only want to remove the inverse association when the inverse
+        # document is in memory.
+        if associated = doc.ivar(inverse)
+          associated.send(_association.setter, nil)
+        end
+      end
+
       # Set the id of the related document in the foreign key field on the
       # keyed document.
       #
@@ -134,6 +181,7 @@ module Mongoid
       # @param [ Document ] doc The document to bind.
       def bind_from_relational_parent(doc)
         check_inverse!(doc)
+        remove_associated(doc)
         bind_foreign_key(doc, record_id(_base))
         bind_polymorphic_type(doc, _base.class.name)
         bind_inverse(doc, _base)
@@ -152,7 +200,7 @@ module Mongoid
       # @example Set the base association.
       #   binding.set_base_association
       #
-      # @return [ true, false ] If the association changed.
+      # @return [ true | false ] If the association changed.
       def set_base_association
         inverse_association = _association.inverse_association(_target)
         if inverse_association != _association && !inverse_association.nil?

data/lib/mongoid/association/builders.rb

@@ -46,9 +46,10 @@ module Mongoid
         association.inverse_class.tap do |klass|
           klass.re_define_method("build_#{association.name}") do |*args|
             attributes, _options = parse_args(*args)
-            document = Factory.build(association.relation_class, attributes)
+            document = Factory.execute_build(association.relation_class, attributes, execute_callbacks: false)
             _building do
               child = send("#{association.name}=", document)
+              child.run_pending_callbacks
               child.run_callbacks(:build)
               child
             end
@@ -69,10 +70,11 @@ module Mongoid
         association.inverse_class.tap do |klass|
           klass.re_define_method("create_#{association.name}") do |*args|
             attributes, _options = parse_args(*args)
-            document = Factory.build(association.relation_class, attributes)
+            document = Factory.execute_build(association.relation_class, attributes, execute_callbacks: false)
             doc = _assigning do
               send("#{association.name}=", document)
             end
+            doc.run_pending_callbacks
             doc.save
             save if new_record? && association.stores_foreign_key?
             doc

data/lib/mongoid/association/constrainable.rb

@@ -5,7 +5,6 @@ module Mongoid
 
     # Used for converting foreign key values to the correct type based on the
     # types of ids that the document stores.
-    #
     module Constrainable
 
       # Convert the supplied object to the appropriate type to set as the

data/lib/mongoid/association/eager_loadable.rb

@@ -20,13 +20,35 @@ module Mongoid
         end
       end
 
-      def preload(relations, docs)
-        relations.group_by(&:inverse_class_name)
-            .values
-            .each do |associations|
-          associations.group_by(&:relation)
-              .each do |relation, association|
-            relation.eager_loader(association, docs).run
+      # Load the associations for the given documents. This will be done
+      # recursively to load the associations of the given documents'
+      # subdocuments.
+      #
+      # @param [ Array<Association> ] associations The associations to load.
+      # @param [ Array<Document> ] document The documents.
+      def preload(associations, docs)
+        assoc_map = associations.group_by(&:inverse_class_name)
+        docs_map = {}
+        queue = [ klass.to_s ]
+
+        while klass = queue.shift
+          if as = assoc_map.delete(klass)
+            as.each do |assoc|
+              queue << assoc.class_name
+
+              # If this class is nested in the inclusion tree, only load documents
+              # for the association above it. If there is no parent association,
+              # we will include documents from the documents passed to this method.
+              ds = docs
+              if assoc.parent_inclusions.length > 0
+                ds = assoc.parent_inclusions.map{ |p| docs_map[p].to_a }.flatten
+              end
+
+              res = assoc.relation.eager_loader([assoc], ds).run
+
+              docs_map[assoc.name] ||= [].to_set
+              docs_map[assoc.name].merge(res)
+            end
           end
         end
       end

data/lib/mongoid/association/embedded/batchable.rb

@@ -50,7 +50,7 @@ module Mongoid
           _unscoped.clear
         end
 
-        # Batch remove the provided documents as a $pullAll.
+        # Batch remove the provided documents as a $pullAll or $pull.
         #
         # @example Batch remove the documents.
         #   batchable.batch_remove([ doc_one, doc_two ])
@@ -58,13 +58,36 @@ module Mongoid
         # @param [ Array<Document> ] docs The docs to remove.
         # @param [ Symbol ] method Delete or destroy.
         def batch_remove(docs, method = :delete)
+          # If the _id is nil, we cannot use $pull and delete by searching for
+          # the id. Therefore we have to use pullAll with the documents'
+          # attributes.
           removals = pre_process_batch_remove(docs, method)
+          pulls, pull_alls = removals.partition { |o| !o["_id"].nil? }
+
+          if !_base.persisted?
+            post_process_batch_remove(docs, method) unless docs.empty?
+            return reindex
+          end
+
           if !docs.empty?
-            collection.find(selector).update_one(
-                positionally(selector, "$pullAll" => { path => removals }),
+            if !pulls.empty?
+              collection.find(selector).update_one(
+                positionally(selector, "$pull" => { path => { "_id" => { "$in" => pulls.pluck("_id") } } }),
                 session: _session
-            )
+              )
+            end
+            if !pull_alls.empty?
+              collection.find(selector).update_one(
+                positionally(selector, "$pullAll" => { path => pull_alls }),
+                session: _session
+              )
+            end
             post_process_batch_remove(docs, method)
+          else
+            collection.find(selector).update_one(
+              positionally(selector, "$set" => { path => [] }),
+              session: _session
+            )
           end
           reindex
         end
@@ -80,7 +103,8 @@ module Mongoid
         def batch_replace(docs)
           if docs.blank?
             if _assigning? && !empty?
-              _base.delayed_atomic_sets.clear
+              _base.delayed_atomic_sets.delete(path)
+              clear_atomic_path_cache
               _base.add_atomic_unset(first)
               target_duplicate = _target.dup
               pre_process_batch_remove(target_duplicate, :delete)
@@ -89,10 +113,11 @@ module Mongoid
               batch_remove(_target.dup)
             end
           elsif _target != docs
-            _base.delayed_atomic_sets.clear unless _assigning?
+            _base.delayed_atomic_sets.delete(path) unless _assigning?
             docs = normalize_docs(docs).compact
             _target.clear and _unscoped.clear
-            _base.delayed_atomic_unsets.clear
+            _base.delayed_atomic_unsets.delete(path)
+            clear_atomic_path_cache
             inserts = execute_batch_set(docs)
             add_atomic_sets(inserts)
           end
@@ -171,7 +196,7 @@ module Mongoid
         # @example Can inserts be performed?
         #   batchable.insertable?
         #
-        # @return [ true, false ] If inserts can be performed.
+        # @return [ true | false ] If inserts can be performed.
         def insertable?
           persistable? && !_assigning? && inserts_valid
         end
@@ -183,7 +208,7 @@ module Mongoid
         # @example Are the inserts currently valid.
         #   batchable.inserts_valid
         #
-        # @return [ true, false ] If inserts are currently valid.
+        # @return [ true | false ] If inserts are currently valid.
         def inserts_valid
           @inserts_valid
         end
@@ -195,9 +220,9 @@ module Mongoid
         # @example Set the flag.
         #   batchable.inserts_valid = true
         #
-        # @param [ true, false ] value The flag.
+        # @param [ true | false ] value The flag.
         #
-        # @return [ true, false ] The flag.
+        # @return [ true | false ] The flag.
         def inserts_valid=(value)
           @inserts_valid = value
         end
@@ -210,7 +235,7 @@ module Mongoid
         # @example Normalize the docs.
         #   batchable.normalize_docs(docs)
         #
-        # @param [ Array<Hash, Document> ] docs The docs to normalize.
+        # @param [ Array<Hash | Document> ] docs The docs to normalize.
         #
         # @return [ Array<Document> ] The docs.
         def normalize_docs(docs)
@@ -234,7 +259,22 @@ module Mongoid
         #
         # @return [ String ] The atomic path.
         def path
-          @path ||= _unscoped.first.atomic_path
+          @path ||= if _unscoped.empty?
+            Mongoid::Atomic::Paths::Embedded::Many.position_without_document(_base, _association)
+          else
+            _unscoped.first.atomic_path
+          end
+        end
+
+        # Clear the cache for path and atomic_paths. This method is used when
+        # the path method is used, and the association has not been set on the
+        # document yet, which can cause path and atomic_paths to be calculated
+        # incorrectly later.
+        #
+        # @api private
+        def clear_atomic_path_cache
+          self.path = nil
+          _base.instance_variable_set("@atomic_paths", nil)
         end
 
         # Set the atomic path.

data/lib/mongoid/association/embedded/cyclic.rb

@@ -88,7 +88,7 @@ module Mongoid
           # @example Determine the child name.
           #   Role.cyclic_child_name
           #
-          # @param [ true, false ] many Is the a many association?
+          # @param [ true | false ] many Is the a many association?
           #
           # @return [ String ] "child_" plus the class name underscored in
           #   singular or plural form.

data/lib/mongoid/association/embedded/embedded_in/binding.rb

@@ -19,12 +19,14 @@ module Mongoid
           #   name.person.bind(:continue => true)
           #   name.person = Person.new
           def bind_one
-            _base._association = _association.inverse_association(_target) unless _base._association
-            _base.parentize(_target)
             binding do
+              check_polymorphic_inverses!(_target)
+              _base._association = _association.inverse_association(_target) unless _base._association
+              _base.parentize(_target)
               if _base.embedded_many?
                 _target.do_or_do_not(_association.inverse(_target)).push(_base)
               else
+                remove_associated(_target)
                 _target.do_or_do_not(_association.inverse_setter(_target), _base)
               end
             end
@@ -45,6 +47,26 @@ module Mongoid
               end
             end
           end
+
+          private
+
+          # Check for problems with multiple inverse definitions.
+          #
+          # @api private
+          #
+          # @example Check for inverses errors.
+          #   binding.check_inverses!(doc)
+          #
+          # @param [ Document ] doc The document to check.
+          def check_polymorphic_inverses!(doc)
+            if inverses = _association.inverses(doc)
+              if inverses.length > 1
+                raise Errors::InvalidSetPolymorphicRelation.new(
+                    _association.name, _base.class.name, _target.class.name
+                )
+              end
+            end
+          end
         end
       end
     end

data/lib/mongoid/association/embedded/embedded_in/proxy.rb

@@ -32,7 +32,7 @@ module Mongoid
           #
           # @param [ Document ] replacement A document to replace the target.
           #
-          # @return [ Document, nil ] The association or nil.
+          # @return [ Document | nil ] The association or nil.
           def substitute(replacement)
             unbind_one
             unless replacement
@@ -74,7 +74,7 @@ module Mongoid
           # @example Can we persist the association?
           #   relation.persistable?
           #
-          # @return [ true, false ] If the association is persistable.
+          # @return [ true | false ] If the association is persistable.
           def persistable?
             _target.persisted? && !_binding? && !_building?
           end