DOCSP-31807: includeResultMetadata option behavior changes for findOneAnd... methods (mongodb#750)

* DOCSP-31807: includeResultMetadata option behavior changes

* MW PR fixes 1

* small fixes

* MW suggestion

Author: rustagir

source/fundamentals/crud/compound-operations.txt

@@ -48,31 +48,37 @@ configurable :ref:`sort <node-fundamentals-sort>` and
 
    Starting in version 5.7, you can set the ``includeResultMetadata``
    setting in the ``options`` object to specify the return type for each
-   of these methods. The setting defaults to ``true``, which means the
-   method returns a ``ModifyResult`` type. If you set
-   ``includeResultMetadata`` to ``false``, the method returns the
-   modified document.
+   of these methods.
+   
+   Starting in version 6.0, this setting defaults to ``false``, which
+   means that each method returns the matched document, or, if no
+   document is matched, it returns ``null``. If you set
+   ``includeResultMetadata`` to ``true``, the method returns a
+   ``ModifyResult`` type that contains the found document and additional
+   metadata.
 
-   Suppose a collection contains the following document:
+   Suppose a collection contains only the following document:
 
    .. code-block:: json
 
       { _id: 1, x: "on" }
 
-   The following code shows the return type for ``findOneAndDelete()``
-   operations when ``includeResultMetadata`` is set to ``true`` and
-   ``false``:
+   The following code shows how the value of the
+   ``includeResultMetadata`` option changes the return type of
+   the ``findOneAndDelete()`` method:
 
    .. code-block:: js
 
+      // default behavior
       // returns { _id: 1, x: 'on' }
-      await coll.findOneAndDelete({ x: "on" }, { includeResultMetadata: false });
+      await coll.findOneAndDelete({ x: "on" });
 
       // returns { lastErrorObject: { n: 1 }, value: { _id: 1, x: 'on' }, ok: 1, ... }
       await coll.findOneAndDelete({ x: "on" }, { includeResultMetadata: true });
 
-      // no document matched, returns null
-      await coll.findOneAndDelete({ x: "off" }, { includeResultMetadata: false });
+      // no document matched
+      // returns null
+      await coll.findOneAndDelete({ x: "off" });
 
 You can set the ``returnDocument`` setting in the ``options`` object for the
 ``findOneAndUpdate()`` and ``findOneAndDelete()`` methods, which lets

source/upgrade.txt

@@ -100,6 +100,8 @@ Version 6.x Breaking Changes
 - If you start a session on a client, then pass that session to a
   different client, the driver throws an error when you
   perform any operations in the session.
+- The ``includeResultMetadata`` option for compound operation methods is
+  ``false`` by default.
 
 .. _node-breaking-changes-v5.x:
 

source/whats-new.txt

@@ -84,6 +84,11 @@ What's New in 6.0
    - If you start a session on a client, then pass that session to a
      different client, the driver throws an error when you
      perform any operations in the session.
+   
+   - The ``includeResultMetadata`` option for compound operation methods
+     is ``false`` by default. See the :ref:`Built-in
+     Methods <node-compound-operations-builtin>` section of the Compound
+     Operations guide for more information.
 
 The {+driver-short+} v6.0 release includes the following features:
 
@@ -199,11 +204,12 @@ The {+driver-short+} v5.7 release includes the following features:
     instead, see the Legacy SSL options deprecated section in the
     v5.7.0 Release Highlights linked at the end of this section.
 
-- A new option for ``findOneAnd...`` compound methods. The ``includeResultMetaData``
+- A new option for compound operation methods. The
+  ``includeResultMetaData``
   option allows you to specify whether to include information about the
-  operation result. See the
-  :ref:`Compound Operations Built-in Methods <node-compound-operations-builtin>`
-  section for more information.
+  operation result. See the :ref:`Built-in Methods
+  <node-compound-operations-builtin>` section of the Compound Operations
+  guide for more information.
 
 - Support for change stream split events which enables processing change
   stream documents that exceed the 16MB maximum BSON size limit.