DOCS-579 batchSize link to limit for negative size and 1

source/reference/method/cursor.batchSize.txt

@@ -7,45 +7,33 @@ cursor.batchSize()
 .. method:: cursor.batchSize()
 
    The :method:`batchSize() <cursor.batchSize()>` method specifies the
-   number of documents the cursor will return in each batch. In most
-   cases, the effect of configuring the batch size will not affect the
-   user or application.
+   number of documents to return in each batch; MongoDB server returns
+   query results in batches. In most cases, the effect of configuring
+   the batch size will not affect the user or the application since the
+   :program:`mongo` shell and most driver present the results
+   seamlessly as though returned in a single batch.
 
    The :method:`batchSize() <cursor.batchSize()>` method takes the
    following parameter:
 
    :param size:
 
-          The number of documents to return per batch. This value
-          also affects whether to close the cursor after the first
-          batch. Refer to the specific driver ``batchSize``
-          documentation for the cursor behavior as determined by the
-          ``size``.
+          The number of documents to return per batch. Do **not** use a
+          batch size of ``1``.
 
-   The :program:`mongo` shell will iterate over 20 documents
-   regardless of the configured batch size, unless you specify a
-   negative batch size.
+   .. note::
+
+      Specifying ``1`` or a negative number is analogous to using the
+      :method:`limit() <cursor.limit()>` method.
 
    Consider the following examples that use the :method:`batchSize()
    <cursor.batchSize()>` method in the :program:`mongo` shell:
 
-   - Set the number of documents returned by the :method:`find()
-     <db.collection.find()>` method to ``10`` per each batch:
+   - Set the batch size so that the results of the :method:`find()` are
+     returned in batches of ``10``. The effects of the batch size is
+     not visible to the user as the :program:`mongo` shell iterate over
+     the first 20 documents:
 
      .. code-block:: javascript
 
-        var curs = db.animals.find().batchSize(10)
-
-     The cursor remains open so that you can iterate through the cursor
-     ``curs`` to access all documents in the ``animals`` collection.
-
-   - Set the number of documents returned by the :method:`find()
-     <db.collection.find()>` method to ``10`` per each batch and close
-     after the first batch:
-
-     .. code-block:: javascript
-
-        var curs = db.animals.find().batchSize(-10)
-
-     In the :program:`mongo` shell, the cursor closes after the first
-     batch so that you can iterate the cursor only ``10`` times.
+        db.animals.find().batchSize(10)