DOCSP-12298 cursor maxAwaitTimeMS (#494)

* DOCSP-12298 Cursor maxAwaitTimeMS

* Staging updates

* Staging updates

* Review feedback

* Staging fixes

* Staging fixes

* Review feedback

* Staging Fixes

* Staging Fixes

* Review feedback

* Review feedback

Author: Dave

source/core/tailable-cursors.txt

@@ -1,3 +1,5 @@
+.. _tailable-cursors-landing-page:
+
 ================
 Tailable Cursors
 ================

source/reference/method/cursor.maxAwaitTimeMS.txt

@@ -0,0 +1,78 @@
+.. _cursor-maxAwaitTimeMS:
+
+=======================
+cursor.maxAwaitTimeMS()
+=======================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. method:: cursor.maxAwaitTimeMS(<time limit>)
+
+   .. include:: /includes/fact-mongosh-shell-method.rst
+
+   Specifies the maximum time for the server to wait for new documents
+   that match a :ref:`tailable cursor <tailable-cursors-landing-page>`
+   query on a :ref:`capped collection <manual-capped-collection>`. For
+   more information on iterating a cursor returned by a query, see:
+   :ref:`read-operations-cursors`.
+
+   The :method:`~cursor.maxAwaitTimeMS()` method has the following
+   prototype form:
+
+   .. code-block:: javascript
+
+      db.collection.find(
+         { <query> },
+         { <projection> }
+      ).tailable( { awaitData: true } ).maxAwaitTimeMS( <milliseconds> )
+
+   The :method:`~cursor.maxAwaitTimeMS()` method has the following
+   parameter:
+
+   .. list-table::
+      :header-rows: 1
+      :widths: 20 20 80
+   
+      * - Parameter
+        - Type
+        - Description
+
+      * - ``milliseconds``
+        - integer
+        - Specifies a maximum wait time for new documents.
+
+.. important::
+
+   This method, :method:`~cursor.maxAwaitTimeMS()`, sets a limit on how
+   long a :ref:`tailable cursor <tailable-cursors-landing-page>` waits
+   for the next response. :method:`~cursor.maxTimeMS()` sets a limit on
+   total processing time.
+
+Example
+--------
+
+Query the :ref:`capped <manual-capped-collection>` ``sales`` collection
+to find agent Mary Kay's weekly sales totals:
+
+.. code-block:: javascript
+   :emphasize-lines: 4
+
+   db.sales.find( 
+      { agent: "Mary Kay" },
+      { _id: 0, agent: 1, weeklyTotal: 1  }
+   ).tailable( { awaitData: true } ).maxAwaitTimeMS( 1000 )
+
+The highlighted line creates a :ref:`tailable cursor
+<tailable-cursors-landing-page>` on the ``sales`` collection. The
+:method:`~cursor.maxAwaitTimeMS()` sets a one second maximum wait time
+for the next cursor update.
+

source/reference/method/cursor.maxTimeMS.txt

@@ -15,37 +15,36 @@ Definition
 
 .. method:: cursor.maxTimeMS(<time limit>)
 
-
    .. include:: /includes/fact-mongosh-shell-method.rst
 
-
    Specifies a cumulative time limit in milliseconds for processing
    operations on a cursor.
 
+   The :method:`~cursor.maxTimeMS()` method has the following prototype
+   form:
+
+   .. code-block:: javascript
+
+      db.collection.find(
+         { <query> },
+         { <projection> }
+      ).maxTimeMS( <milliseconds> )
+
    The :method:`~cursor.maxTimeMS()` method has the following
    parameter:
 
-
    .. list-table::
       :header-rows: 1
       :widths: 20 20 80
 
       * - Parameter
-   
         - Type
-   
         - Description
-   
+
       * - ``milliseconds``
-   
         - integer
-   
         - Specifies a cumulative time limit in milliseconds for processing operations
           on the cursor.
-          
-          
-   
-
 
 .. important::
 
@@ -55,6 +54,12 @@ Definition
    to idle time. A cursor's idle time does not contribute towards its
    processing time.
 
+   The :method:`~cursor.maxAwaitTimeMS()` method sets a limit on how
+   long a :ref:`tailable cursor <tailable-cursors-landing-page>` waits
+   for the next response. It does not set a limit on total processing
+   time.
+
+
 Behaviors
 ---------
 
@@ -140,3 +145,4 @@ Examples
    .. code-block:: javascript
 
       db.collection.find({description: /August [0-9]+, 1969/}).maxTimeMS(50)
+

source/reference/method/js-cursor.txt

@@ -75,6 +75,9 @@ These methods modify the way that the underlying query is executed.
    * - :method:`cursor.max()`
      - Specifies an exclusive upper index bound for a cursor. For use
        with :method:`cursor.hint()`
+   * - :method:`cursor.maxAwaitTimeMS()`
+     - Specifies a limit in milliseconds to wait for the next query
+       result update.
    * - :method:`cursor.maxTimeMS()`
      - Specifies a cumulative time limit in milliseconds for processing
        operations on a cursor.
@@ -141,6 +144,7 @@ These methods modify the way that the underlying query is executed.
    /reference/method/cursor.limit
    /reference/method/cursor.map
    /reference/method/cursor.max
+   /reference/method/cursor.maxAwaitTimeMS
    /reference/method/cursor.maxTimeMS
    /reference/method/cursor.min
    /reference/method/cursor.next