DOCSP 21855 clarifying/updating updateMany and set (aggregation) examples (#1507)

* DOCSP-21855 updating updateMany and set(aggregation) examples

* DOCSP-21855 updating updateMany and set(aggregation) examples

* DOCSP-21855 updating updateMany and set(aggregation) examples

* DOCSP-21855 formatting fixes

* DOCSP-21855 formatting fixes

* DOCSP-21855 formatting fixes

* DOCSP-21855 wording update

Author: ltran-mdb

source/reference/method/db.collection.updateMany.txt

@@ -395,8 +395,8 @@ Using the aggregation pipeline allows for a more expressive update
 statement, such as expressing conditional updates based on current
 field values or updating one field using the value of another field(s).
 
-Example 1
-`````````
+Example 1: Update with Aggregation Pipeline Using Existing Fields
+`````````````````````````````````````````````````````````````````
 
 The following examples uses the aggregation pipeline to modify a field
 using the values of the other fields in the document.
@@ -458,8 +458,8 @@ After the command, the collection contains the following documents:
    { "_id" : 1, "member" : "abc123", "status" : "Modified", "points" : 2, "lastUpdate" : ISODate("2020-01-23T05:50:49.247Z"), "comments" : [ "note to self: confirm status", "Need to activate" ] }
    { "_id" : 2, "member" : "xyz123", "status" : "Modified", "points" : 60, "lastUpdate" : ISODate("2020-01-23T05:50:49.247Z"), "comments" : [ "reminder: ping me at 100pts", "Some random comment" ] }
 
-Example 2
-`````````
+Example 2: Update with Aggregation Pipeline Using Existing Fields Conditionally
+```````````````````````````````````````````````````````````````````````````````
 
 The aggregation pipeline allows the update to perform conditional
 updates based on the current field values as well as use current field

source/reference/operator/aggregation/set.txt

@@ -247,3 +247,52 @@ The operation returns the following:
    :copyable: false
 
    { "_id" : 1, "student" : "Maya", "homework" : [ 10, 5, 10, 7 ], "quiz" : [ 10, 8 ], "extraCredit" : 0 }
+
+Creating a New Field with Existing Fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create a sample ``scores`` collection with the following:
+
+.. code-block:: javascript
+
+   db.scores.insertMany([
+      { _id: 1, student: "Maya", homework: [ 10, 5, 10 ], quiz: [ 10, 8 ], extraCredit: 0 },
+      { _id: 2, student: "Ryan", homework: [ 5, 6, 5 ], quiz: [ 8, 8 ], extraCredit: 8 }
+   ])
+
+The following aggregation operation adds a new field ``quizAverage`` 
+to each document that contains the average of the ``quiz`` array.
+
+.. code-block:: javascript
+
+   db.scores.aggregate( [
+      {
+         $set: {
+            quizAverage: { $avg: "$quiz" } 
+         }
+      }
+   ] )
+
+The operation returns the following documents:
+
+.. code-block:: javascript
+   :copyable: false
+
+   [
+      {
+         _id: 1,
+         student: 'Maya',
+         homework: [ 10, 5, 10 ],
+         quiz: [ 10, 8 ],
+         extraCredit: 0,
+         quizAverage: 9
+      },
+      {
+         _id: 2,
+         student: 'Ryan',
+         homework: [ 5, 6, 5 ],
+         quiz: [ 8, 8 ],
+         extraCredit: 8,
+         quizAverage: 8
+      }
+   ]