DOCSP-10199: cursor feedback fixes (#94)

* DOCSP-10199: cursor feedback fixes

Author: Chris Cho

source/code-snippets/crud/cursor.js

@@ -53,6 +53,7 @@ async function streamAPI(collection) {
 async function eventAPI(collection) {
   // start event cursor example
   const cursor = collection.find({});
+  // the "data" event is fired once per document
   cursor.on("data", data => console.log(data));
   // end event cursor example
 }

source/fundamentals/crud.txt

@@ -90,6 +90,8 @@ set for viewing.
       :end-before: end aggregate crud example
       :dedent: 4
 
+.. _watch-subscribe:
+
 Watch / Subscribe
 ~~~~~~~~~~~~~~~~~
 

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

@@ -24,10 +24,10 @@ The following functions directly return cursors:
 
 - ``Db.listCollections()``
 
-Other methods, like :doc:`Collection.findOne()
-</usage-examples/findOne>` and ``Collection.watch()``,
-use cursors to return results but do not directly expose those
-cursors to the method caller.
+Other methods such as :doc:`Collection.findOne() </usage-examples/findOne>`
+and :doc:`Collection.watch() </fundamentals/crud#watch-subscribe>` use
+cursors internally, and return the results of the operations instead of
+a cursor.
 
 Cursor Paradigms
 ----------------
@@ -52,6 +52,12 @@ pulling all matching documents into a collection in process memory.
    undefined behaviour. Always wait for the previous
    asynchronous operation to complete before running another.
 
+.. note::
+
+   When you reach the last result through iteration or through an at-once
+   fetch, the cursor is exhausted which means it ceases to respond to methods
+   that access the results.
+   
 For Each Functional Iteration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -95,8 +101,9 @@ method to retrieve the subsequent element of the cursor:
 Stream API
 ~~~~~~~~~~
 
-All cursors are Node Readable Streams operating in Object Mode. Cursors
-will work with most Node stream APIs:
+All cursors are Node Readable Streams that operate in **Object Mode** which
+passes JavaScript objects rather than Buffers or Strings through the
+pipeline. Cursors work with most Node stream APIs:
 
 .. literalinclude:: /code-snippets/crud/cursor.js
    :language: javascript
@@ -131,6 +138,7 @@ exceeding memory constraints.
    :end-before: end fetchAll cursor example
    :dedent: 4
 
+
 Cursor Utility Methods
 ----------------------