DOCSP-20004 updates for update pt3 v5.1 (#112) (#115)

* DOCSP-20004 updates for update pt3

* Clarify bit layout

* Better find commands

* Review comments

Author: Dave

source/includes/fact-bulkwrite-explainable.rst

@@ -61,7 +61,7 @@ collection, the following operation inserts a document with the field
 
 .. code-block:: javascript
 
-   db.products.update(
+   db.products.updateOne(
       { _id: 1 },
       {
         $set: { item: "apple" },

source/reference/method/Date.txt

@@ -24,6 +24,15 @@ Definition
       - :method:`db.collection.update()`
       - :method:`db.collection.remove()`
 
+   .. note::
+
+     :method:`db.collection.insert()` and
+     :method:`db.collection.update()` are deprecated. 
+     
+     The results returned by the replacement methods have a different
+     format. For output similar to :method:`WriteResult`, consider
+     using :method:`db.collection.bulkWrite()`.
+
 Properties
 ----------
 
@@ -106,3 +115,4 @@ The :method:`WriteResult` has the following properties:
 
    - :method:`WriteResult.hasWriteError()`
    - :method:`WriteResult.hasWriteConcernError()`
+

source/reference/method/WriteResult.txt

@@ -131,14 +131,8 @@ unique within the collection to avoid duplicate key error.
 Explainability
 ~~~~~~~~~~~~~~
 
-
-.. Broke out to be used in the new CRUD API docs
-
-.. |write-method| replace:: :method:`~db.collection.insertMany()`
-.. |old-write-method| replace:: :method:`~db.collection.insert()`
-
-.. include:: /includes/fact-bulkwrite-explainable.rst
-
+:method:`~db.collection.insertMany()` is not compatible with 
+:method:`db.collection.explain()`.
 
 Error Handling
 ~~~~~~~~~~~~~~

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

@@ -102,11 +102,8 @@ unique within the collection to avoid duplicate key error.
 Explainability
 ~~~~~~~~~~~~~~
 
-.. |write-method| replace:: :method:`~db.collection.insertOne()`
-.. |old-write-method| replace:: :method:`~db.collection.insert()`
-
-
-.. include:: /includes/fact-bulkwrite-explainable.rst
+:method:`~db.collection.insertOne()` is not compatible with 
+:method:`db.collection.explain()`.
 
 Error Handling
 ~~~~~~~~~~~~~~

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

@@ -307,10 +307,8 @@ full shard key in the ``filter``.
 Explainability
 ~~~~~~~~~~~~~~
 
-.. |write-method| replace:: :method:`~db.collection.updateMany()`
-.. |old-write-method| replace:: :method:`~db.collection.update()`
-
-.. include:: /includes/fact-bulkwrite-explainable.rst
+:method:`~db.collection.updateMany()` is not compatible with 
+:method:`db.collection.explain()`.
 
 Transactions
 ~~~~~~~~~~~~

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

@@ -17,12 +17,8 @@ Definition
 
 .. method:: db.collection.updateOne(filter, update, options)
 
-
    .. include:: /includes/fact-mongosh-shell-method.rst
 
-
-   .. versionadded:: 3.2
-
    Updates a single document within the collection based on the filter.
 
 Syntax
@@ -384,10 +380,8 @@ See also:
 Explainability
 ~~~~~~~~~~~~~~
 
-.. |write-method| replace:: :method:`~db.collection.updateOne()`
-.. |old-write-method| replace:: :method:`~db.collection.update()`
-
-.. include:: /includes/fact-bulkwrite-explainable.rst
+:method:`~db.collection.updateOne()` is not compatible with 
+:method:`db.collection.explain()`.
 
 Transactions
 ~~~~~~~~~~~~

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

@@ -206,17 +206,17 @@ to add delivery dates to the documents:
 
 .. code-block:: javascript
 
-   db.shipping.update(
+   db.shipping.updateOne(
       { custId: 456 },
       { $set: { deliveryDate: ISODate( "2021-01-10" ) } }
    )
 
-   db.shipping.update(
+   db.shipping.updateOne(
      { custId: 457 },
      { $set: { deliveryDate:  ISODate( "2021-03-01" ) } }
    )
 
-   db.shipping.update(
+   db.shipping.updateOne(
       { custId: 458 },
       { $set: { deliveryDate:  ISODate( "2021-03-02" ) } }
    )

source/reference/operator/aggregation/dateAdd.txt

@@ -47,119 +47,125 @@ Behavior
 Examples
 --------
 
-Bitwise AND
-~~~~~~~~~~~
-
-Consider the following document inserted into the collection
-``switches``:
+The following examples use the ``switches`` collection:
 
 .. code-block:: javascript
 
-   { _id: 1, expdata: NumberInt(13) }
+   db.switches.insertMany( [
+      { _id: 1, expdata: Int32(13) },
+      { _id: 2, expdata: Int32(3) },
+      { _id: 3, expdata: Int32(1) }
+   ] )
+
+Bitwise AND
+~~~~~~~~~~~
 
-The following :method:`~db.collection.update()` operation updates the
-``expdata`` field to the result of a bitwise ``and`` operation between
-the current value ``NumberInt(13)`` (i.e. ``1101``) and
-``NumberInt(10)`` (i.e. ``1010``):
+Use a bitwise ``and`` in the :method:`~db.collection.updateOne()`
+operation to update ``expdata``.
 
 .. code-block:: javascript
 
-   db.switches.update(
+   db.switches.updateOne(
       { _id: 1 },
-      { $bit: { expdata: { and: NumberInt(10) } } }
+      { $bit: { expdata: { and: Int32( 10 ) } } }
    )
 
-The bitwise ``and`` operation results in the integer 8 (i.e. ``1000``):
+The bitwise ``and`` operation:
 
-.. code-block:: none
+- gets the bitwise value of ``expdata``
+- uses ``and`` to apply the bitwise value of Int32(10)
+- updates ``expdata`` with the result, 1000
 
-   1101
-   1010
+.. code-block:: javascript
+   :copyable: false
+
+   1101   // expdata
+   1010   // Int32(10)
    ----
    1000
 
-And the updated document has the following value for ``expdata``:
+Binary 1000 is equivalent to Int32(8). The
+``db.switches.find( { _id: 1 } )`` command returns the following
+document:
 
 .. code-block:: javascript
 
    { "_id" : 1, "expdata" : 8 }
 
-:binary:`~bin.mongosh` displays ``NumberInt(8)`` as ``8``.
 
 Bitwise OR
 ~~~~~~~~~~
 
-Consider the following document inserted into the collection
-``switches``:
-
-.. code-block:: javascript
-
-   { _id: 2, expdata: NumberLong(3) }
-
-The following :method:`~db.collection.update()` operation updates the
-``expdata`` field to the result of a bitwise ``or`` operation between
-the current value ``NumberLong(3)`` (i.e. ``0011``) and
-``NumberInt(5)`` (i.e. ``0101``):
+Use a bitwise ``or`` in the :method:`~db.collection.updateOne()`
+operation to update ``expdata``.
 
 .. code-block:: javascript
 
-   db.switches.update(
+   db.switches.updateOne(
       { _id: 2 },
-      { $bit: { expdata: { or: NumberInt(5) } } }
+      { $bit: { expdata: { or: Int32( 5 ) } } }
    )
 
-The bitwise ``or`` operation results in the integer 7 (i.e. ``0111``):
+The bitwise ``or`` operation:
+
+- gets the bitwise value of ``expdata``
+- uses ``or`` to apply the bitwise value of Int32(5)
+- updates ``expdata`` with the result, 0111
 
-.. code-block:: none
+.. code-block:: javascript
+   :copyable: false
 
-   0011
-   0101
+   0111   // expdata
+   0101   // Int32(5)
    ----
    0111
 
-And the updated document has the following value for ``expdata``:
+Binary 0111 is equivalent to Int32(7). The 
+``db.switches.find( { _id: 2 } )`` command returns the following
+document:
 
 .. code-block:: javascript
 
-   { "_id" : 2, "expdata" : NumberLong(7) }
+   { "_id" : 2, "expdata" : 7 }
+
 
 Bitwise XOR
 ~~~~~~~~~~~
 
-Consider the following document in the collection ``switches``:
+Use a bitwise ``xor`` in the :method:`~db.collection.updateOne()`
+operation to update ``expdata``.
 
 .. code-block:: javascript
 
-   { _id: 3, expdata: NumberLong(1) }
-
-The following :method:`~db.collection.update()` operation updates the
-``expdata`` field to the result of a bitwise ``xor`` operation between
-the current value ``NumberLong(1)`` (i.e. ``0001``) and
-``NumberInt(5)`` (i.e. ``0101``):
-
-.. code-block:: javascript
-
-   db.switches.update(
+   db.switches.updateOne(
       { _id: 3 },
-      { $bit: { expdata: { xor: NumberInt(5) } } }
+      { $bit: { expdata: { xor: Int32( 5 ) } } }
    )
 
-The bitwise ``xor`` operation results in the integer 4:
+The bitwise ``and`` operation:
 
-.. code-block:: none
+- gets the bitwise value of ``expdata``
+- uses ``and`` to apply the bitwise value of Int32(5)
+- updates ``expdata`` with the result, 0100
 
-   0001
-   0101
+.. code-block:: javascript
+   :copyable: false
+
+   0001   // expdata
+   0101   // Int32(5)
    ----
    0100
 
-And the updated document has the following value for ``expdata``:
+Binary 0100 is equivalent to ``Int32(4)``. The
+``db.switches.find( { _id: 3 } )`` command returns the following
+document:
 
 .. code-block:: javascript
 
-   { "_id" : 3, "expdata" : NumberLong(4) }
+   { "_id" : 1, "expdata" : 4 }
 
 .. seealso::
 
-   - :method:`db.collection.update()`
+   - :method:`db.collection.updateOne()`
    - :method:`db.collection.findAndModify()`
+