MONGOID-5391 improve pluck documentation, add tests (#5399)

* MONGOID-5391 improve documentation for pluck

* additional tests

Co-authored-by: shields <[email protected]>
Co-authored-by: Oleg Pudeyev <[email protected]>

Author: 3 people

docs/reference/queries.txt

@@ -1412,12 +1412,20 @@ Mongoid also has some helpful methods on criteria.
         .. code-block:: ruby
 
           Band.all.pluck(:name)
+            #=> ["Daft Punk", "Aphex Twin", "Ween"]
 
-          Band.all.pluck('cities.name')
+          Band.all.pluck('address.city')
+            #=> ["Paris", "Limerick", "New Hope"]
 
           # Using the earlier definition of Manager,
           # expands out to "managers.name" in the query:
           Band.all.pluck('managers.n')
+            #=> [ ["Berry Gordy", "Tommy Mottola"], [], ["Quincy Jones"] ]
+
+          # Accepts multiple field arguments, in which case
+          # the result will be returned as an Array of Arrays.
+          Band.all.pluck(:name, :likes)
+            #=> [ ["Daft Punk", 342], ["Aphex Twin", 98], ["Ween", 227] ]
 
    * - ``Criteria#take``
 

lib/mongoid/contextual/mongo.rb

@@ -391,15 +391,22 @@ def map_reduce(map, reduce)
         MapReduce.new(collection, criteria, map, reduce)
       end
 
-      # Pluck the single field values from the database. Will return duplicates
-      # if they exist and only works for top level fields.
+      # Pluck the field value(s) from the database. Returns one
+      # result for each document found in the database for
+      # the context. The results are normalized according to their
+      # Mongoid field types. Note that the results may include
+      # duplicates and nil values.
       #
       # @example Pluck a field.
       #   context.pluck(:_id)
       #
-      # @param [ String | Symbol ] *fields Field(s) to pluck.
+      # @param [ String | Symbol ] *fields Field(s) to pluck,
+      #   which may include nested fields using dot-notation.
       #
       # @return [ Array<Object> | Array<Array<Object>> ] The plucked values.
+      #   If the *fields arg contains a single value, each result
+      #   in the array will be a single value. Otherwise, each
+      #   result in the array will be an array of values.
       def pluck(*fields)
         # Multiple fields can map to the same field name. For example, plucking
         # a field and its _translations field map to the same field in the database.

spec/mongoid/contextual/memory_spec.rb

@@ -1243,11 +1243,11 @@
       config_override :legacy_pluck_distinct, true
 
       let(:hobrecht) do
-        Address.new(street: "hobrecht")
+        Address.new(street: "hobrecht", number: 213)
       end
 
       let(:friedel) do
-        Address.new(street: "friedel")
+        Address.new(street: "friedel", number: 11)
       end
 
       let(:criteria) do
@@ -1267,6 +1267,17 @@
         end
       end
 
+      context "when plucking multiple fields" do
+
+        let!(:plucked) do
+          context.pluck(:street, :number)
+        end
+
+        it "returns the values as an array" do
+          expect(plucked).to eq([ ["hobrecht", 213], ["friedel", 11] ])
+        end
+      end
+
       context "when plucking a mix of empty and non-empty values" do
 
         let(:empty_doc) do
@@ -1296,7 +1307,7 @@
             context.pluck(:foo)
           end
 
-          it "returns a empty array" do
+          it "returns an empty array" do
             expect(plucked).to eq([nil, nil])
           end
         end
@@ -1307,7 +1318,7 @@
             context.pluck(:foo, :bar)
           end
 
-          it "returns a empty array" do
+          it "returns an empty array" do
             expect(plucked).to eq([[nil, nil], [nil, nil]])
           end
         end
@@ -1720,7 +1731,7 @@
         end
       end
 
-      context "when tallying deeply nested arrays/embedded associations" do
+      context "when plucking deeply nested arrays/embedded associations" do
 
         let(:criteria) do
           Person.all.tap do |crit|

spec/mongoid/contextual/none_spec.rb

@@ -54,8 +54,17 @@
   end
 
   describe "#pluck" do
-    it "returns an empty array" do
-      expect(context.pluck(:id)).to eq([])
+
+    context "when plucking one field" do
+      it "returns an empty array" do
+        expect(context.pluck(:id)).to eq([])
+      end
+    end
+
+    context "when plucking multiple fields" do
+      it "returns an empty array" do
+        expect(context.pluck(:id, :foo)).to eq([])
+      end
     end
   end