DOCSP-35926: surface combine information (#542)

* DOCSP-35926: surface combine information

* fix

(cherry picked from commit 5432fbb)

Author: rustagir

source/fundamentals/builders/updates.txt

@@ -2,8 +2,6 @@
 Updates Builders
 ================
 
-.. default-domain:: mongodb
-
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -15,16 +13,17 @@ Updates Builders
 Overview
 --------
 
-In this guide, you can learn how to specify **updates** using
-:doc:`builders </fundamentals/builders/>` in the MongoDB Java driver.
+In this guide, you can learn how to specify **updates** by using
+:ref:`builders <java-builders>` in the {+driver-short+}.
 
-The ``Updates`` builder provides helper methods for the following types of updates:
+The ``Updates`` builder provides helper methods to simplify the following
+tasks:
 
-- :ref:`Field Updates <field_updates>`
-- :ref:`Array Updates <array_updates>`
-- :ref:`Combining Multiple Update Operators <multiple_updates>`
+- :ref:`field_updates`: Updating or removing the value of a particular field
+- :ref:`array_updates`: Updating values in an array-valued field
+- :ref:`multiple_updates`: Performing multiple updates at once, such as setting or changing more than one field
 
-Some methods that expect updates are:
+Some methods that expect update documents are:
 
 - ``updateOne()``
 - ``updateMany()``
@@ -36,7 +35,9 @@ type, which you can pass to any method that expects an update argument.
 
 .. tip::
 
-   For brevity, you may choose to import the methods of the `Updates <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Updates.html>`__ class statically:
+   For brevity, you can choose to import the methods of the `Updates
+   <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Updates.html>`__
+   class statically:
 
    .. code-block:: java
 
@@ -88,6 +89,29 @@ The preceding example updates the original document to the following state:
       "lastModified": { "$date": "2021-03-05T05:00:00Z" }
    }
 
+The following example adds two new fields to the original document:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/builders/Updates.java
+   :language: java
+   :dedent:
+   :start-after: begin combineSet
+   :end-before: end combineSet
+
+The preceding example updates the original document to the following state:
+
+.. code-block:: json
+   :copyable: false
+
+   {
+      "_id": 1,
+      "color": "red",
+      "qty": 5,
+      "vendor": [ "A", "D", "M" ],
+      "lastModified": { "$date": "2021-03-05T05:00:00Z" },
+      "width": 6.5,
+      "height": 10,
+   }
+
 Unset
 ~~~~~
 Use the `unset() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Updates.html#unset(java.lang.String)>`__ method

source/includes/fundamentals/code-snippets/builders/Updates.java

@@ -43,6 +43,10 @@ public static void main(String[] args) {
         updates.setUpdate();
         updates.resetCollection(updates);
 
+        System.out.println("combineSet:");
+        updates.combineSet();
+        updates.resetCollection(updates);
+
         System.out.println("unsetUpdate:");
         updates.unsetUpdate();
         updates.resetCollection(updates);
@@ -116,6 +120,15 @@ private void setUpdate() {
         collection.updateOne(filter, update);
         // end setUpdate
     }
+
+    private void combineSet() {
+        // begin combineSet
+        Bson filter = eq("_id", 1);
+        Bson update = combine(set("width", 6.5), set("height", 10));
+        collection.updateOne(filter, update);
+        // end combineSet
+    }
+
     private void unsetUpdate() {
         // begin unsetUpdate
         Bson filter = eq("_id", 1);