DOCSP-17340 cursor updates (#200)

* DOCSP-17340: updates and additions to make access to cursor information easier

* DOCSP-17340: updates and additions to make access to cursor information easier

* DOCSP-17340: added cursor access note to more pages

Author: rustagir

source/fundamentals/crud/query-document.txt

@@ -45,6 +45,8 @@ examples:
      { "_id": 4, "name": "avocados", "qty": 3, "rating": 5 },
    ]);
 
+.. include:: /includes/access-cursor-note.rst
+
 Literal Value Queries
 ---------------------
 

source/fundamentals/crud/read-operations/cursor.txt

@@ -79,6 +79,21 @@ results in a functional style:
    :start-after: start foreach cursor example
    :end-before: end foreach cursor example
 
+Return an Array of All Documents
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For use cases that require all documents matched by a query to be held
+in memory at the same time, use :node-api-4.0:`toArray() </classes/findcursor.html#toarray>`. 
+Note that large numbers of matched documents can cause performance issues
+or failures if the operation exceeds memory constraints. Consider using
+:node-api-4.0:`forEach() </classes/findcursor.html#foreach>` to iterate
+through results unless you want to return all documents at once. 
+
+.. literalinclude:: /code-snippets/crud/cursor.js
+   :language: javascript
+   :start-after: start fetchAll cursor example
+   :end-before: end fetchAll cursor example
+
 Asynchronous Iteration
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -126,20 +141,6 @@ As Readable Streams, cursors also support the Event API's
    :start-after: start event cursor example
    :end-before: end event cursor example
 
-Fetch All Documents At Once
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For use cases that require all documents matched by a query to be held
-in memory at the same time, use :node-api-4.0:`toArray() </classes/findcursor.html#toarray>`. 
-Note that large sets of matched documents can cause performance issues or even
-failures due to exceeding memory constraints.
-
-.. literalinclude:: /code-snippets/crud/cursor.js
-   :language: javascript
-   :start-after: start fetchAll cursor example
-   :end-before: end fetchAll cursor example
-
-
 Cursor Utility Methods
 ----------------------
 

source/fundamentals/crud/read-operations/limit.txt

@@ -41,6 +41,8 @@ describe books:
      { "_id": 6, "name": "A Dance With Dragons", "author": "Tolkein", "length": 1104 },
    ]
 
+.. include:: /includes/access-cursor-note.rst
+
 Limit
 -----
 

source/fundamentals/crud/read-operations/project.txt

@@ -43,6 +43,8 @@ varieties of fruit:
      { "_id": 4, "name": "avocados", "qty": 3, "rating": 5 },
    ]
 
+.. include:: /includes/access-cursor-note.rst
+
 Single Field
 ------------
 

source/fundamentals/crud/read-operations/retrieve.txt

@@ -35,6 +35,8 @@ If you want to monitor the database for incoming data that matches a set of
 criteria, you can use the watch operation to be notified in real-time when 
 matching data is inserted.
 
+.. include:: /includes/access-cursor-note.rst
+
 Find
 ----
 

source/fundamentals/crud/read-operations/skip.txt

@@ -42,6 +42,8 @@ fruit:
       { "_id": 4, "name": "avocados", "qty": 3, "rating": 5 },
    ]
 
+.. include:: /includes/access-cursor-note.rst
+
 Example
 -------
 

source/fundamentals/crud/read-operations/sort.txt

@@ -40,6 +40,8 @@ insert this data into a collection, run the following operation:
      { "_id": 6, "name": "A Dance with Dragons", "author": "Martin", "length": 1104 },
    ]);
 
+.. include:: /includes/access-cursor-note.rst
+
 Example
 -------
 

source/fundamentals/crud/read-operations/text.txt

@@ -153,6 +153,8 @@ Querying with the negated term yields the following documents:
    { title: 'Star Trek III: The Search for Spock' }
    { title: 'Star Trek II: The Wrath of Khan' }
 
+.. include:: /includes/access-cursor-note.rst
+
 Sort by Relevance
 ~~~~~~~~~~~~~~~~~
 

source/includes/access-cursor-note.rst

@@ -0,0 +1,6 @@
+.. note::
+
+   Your query operation may return a reference to a
+   cursor that contains matching documents. To learn how to
+   examine data stored in the cursor, see the
+   :doc:`Cursor Fundamentals page </fundamentals/crud/read-operations/cursor>`.