MONGOID-5610 - Cleanup: Use delegator for exists? on embedded proxy, and add code comments

lib/mongoid/association/embedded/embeds_many/proxy.rb

@@ -292,6 +292,16 @@ def destroy_all(conditions = {})
           # @example Are there persisted documents?
           #   person.posts.exists?
           #
+          # @example Is a document with the given id persisted?
+          #   person.posts.exists?(BSON::ObjectId(...))
+          #
+          # @example Are there persisted documents with the given title?
+          #   person.posts.exists?({ title: "50 Ways to Leave Your Lover" })
+          #
+          # @example Return false if nil is given.
+          #   missing_post = nil
+          #   person.posts.exists?(missing_post&._id) #=> false
+          #
           # @param [ :none | nil | false | Hash | Object ] id_or_conditions
           #   When :none (the default), returns true if any persisted
           #   documents exist in the association. When nil or false, this

lib/mongoid/association/referenced/has_many/proxy.rb

@@ -36,7 +36,7 @@ def embedded?
 
           extend ClassMethods
 
-          def_delegator :criteria, :count
+          def_delegators :criteria, :count, :exists?
           def_delegators :_target, :first, :in_memory, :last, :reset, :uniq
 
           # Instantiate a new references_many association. Will set the foreign key
@@ -205,32 +205,6 @@ def each(&block)
             end
           end
 
-          # Determine if any documents in this association exist in the database.
-          #
-          # If the association contains documents but all of the documents
-          # exist only in the application, i.e. have not been persisted to the
-          # database, this method returns false.
-          #
-          # This method queries the database on each invocation even if the
-          # association is already loaded into memory.
-          #
-          # @example Are there persisted documents?
-          #   person.posts.exists?
-          #
-          # @param [ :none | nil | false | Hash | Object ] id_or_conditions
-          #   When :none (the default), returns true if any persisted
-          #   documents exist in the association. When nil or false, this
-          #   will always return false. When a Hash is given, this queries
-          #   the documents in the association for those that match the given
-          #   conditions, and returns true if any match. Any other argument is
-          #   interpreted as an id, and queries for the existence of documents
-          #   in the association with a matching _id.
-          #
-          # @return [ true | false ] True is persisted documents exist, false if not.
-          def exists?(id_or_conditions = :none)
-            criteria.exists?(id_or_conditions)
-          end
-
           # Find the matching document on the association, either based on id or
           # conditions.
           #

lib/mongoid/contextual/memory.rb

@@ -118,8 +118,13 @@ def each
       # @example Do any documents exist for given conditions.
       #   context.exists?(name: "...")
       #
-      # @param [ Hash | Object | false ] id_or_conditions an _id to
-      #   search for, a hash of conditions, nil or false.
+      # @example Always return false.
+      #   context.exists?(false)
+      #
+      # @param [ :none | Hash | BSON::ObjectId | nil | false ] id_or_conditions
+      #   May optionally supply search conditions as a hash or an object id.
+      #   Will always return false when given nil or false. The symbol :none is
+      #   the default when argument is not supplied.
       #
       # @return [ true | false ] If the count is more than zero.
       #   Always false if passed nil or false.

lib/mongoid/contextual/mongo.rb

@@ -179,11 +179,16 @@ def each(&block)
       # @example Do any documents exist for given conditions.
       #   context.exists?(name: "...")
       #
+      # @example Always return false.
+      #   context.exists?(false)
+      #
       # @note We don't use count here since Mongo does not use counted
       #   b-tree indexes.
       #
-      # @param [ Hash | Object | false ] id_or_conditions an _id to
-      #   search for, a hash of conditions, nil or false.
+      # @param [ :none | Hash | BSON::ObjectId | nil | false ] id_or_conditions
+      #   May optionally supply search conditions as a hash or an object id.
+      #   Will always return false when given nil or false. The symbol :none is
+      #   the default when argument is not supplied.
       #
       # @return [ true | false ] If the count is more than zero.
       #   Always false if passed nil or false.

lib/mongoid/contextual/none.rb

@@ -58,7 +58,7 @@ def each
         end
       end
 
-      # Do any documents exist for the context.
+      # Do any documents exist for the null context.
       #
       # @example Do any documents exist in the null context.
       #   context.exists?
@@ -69,11 +69,14 @@ def each
       # @example Do any documents exist for given conditions.
       #   context.exists?(name: "...")
       #
-      # @param [ Hash | Object | false ] id_or_conditions an _id to
-      #   search for, a hash of conditions, nil or false.
+      # @example Always return false.
+      #   context.exists?(false)
+      #
+      # @param [ :none | Hash | BSON::ObjectId | nil | false ] _id_or_conditions
+      #   Not used in null context.
       #
       # @return [ false ] Always false.
-      def exists?(id_or_conditions = :none); false; end
+      def exists?(_id_or_conditions = :none); false; end
 
       # Pluck the field values in null context.
       #

lib/mongoid/findable.rb

@@ -107,8 +107,14 @@ def empty?
     # @example Do any documents exist for given conditions.
     #   Person.exists?(name: "...")
     #
-    # @param [ Hash | Object | false ] id_or_conditions an _id to
-    #   search for, a hash of conditions, nil or false.
+    # @example Return false if nil is given.
+    #   missing_person = nil
+    #   Person.exists?(missing_person&._id) #=> false
+    #
+    # @param [ :none | Hash | BSON::ObjectId | nil | false ] id_or_conditions
+    #   May optionally supply search conditions as a hash or an object id.
+    #   Will always return false when given nil or false. The symbol :none is
+    #   the default when argument is not supplied.
     #
     # @return [ true | false ] If any documents exist for the conditions.
     #   Always false if passed nil or false.