PYTHON-894 - More doc clarifications for alive.

pymongo/command_cursor.py

@@ -157,11 +157,16 @@ class CommandCursor(object):
     def alive(self):
         """Does this cursor have the potential to return more data?
 
-        Even if :attr:`alive` is ``True``, :meth:`.next` can raise
+        Even if :attr:`alive` is ``True``, :meth:`next` can raise
         :exc:`StopIteration`. Best to use a for loop::
 
             for doc in collection.aggregate(pipeline):
                 print(doc)
+
+        .. note:: :attr:`alive` can be True while iterating a cursor from
+          a failed server. In this case :attr:`alive` will return False after
+          :meth:`next` fails to retrieve the next batch of results from the
+          server.
         """
         return bool(len(self.__data) or (not self.__killed))
 
@@ -174,8 +179,7 @@ class CommandCursor(object):
         return self
 
     def next(self):
-        """Advance the cursor.
-        """
+        """Advance the cursor."""
         if len(self.__data) or self._refresh():
             coll = self.__collection
             return coll.database._fix_outgoing(self.__data.popleft(), coll)

pymongo/cursor.py

@@ -1057,6 +1057,12 @@ class Cursor(object):
             for doc in collection.find():
                 print(doc)
 
+        .. note:: Even if :attr:`alive` is True, :meth:`next` can raise
+          :exc:`StopIteration`. :attr:`alive` can also be True while iterating
+          a cursor from a failed server. In this case :attr:`alive` will
+          return False after :meth:`next` fails to retrieve the next batch
+          of results from the server.
+
         .. versionadded:: 1.5
         """
         return bool(len(self.__data) or (not self.__killed))
@@ -1077,6 +1083,7 @@ class Cursor(object):
         return self
 
     def next(self):
+        """Advance the cursor."""
         if self.__empty:
             raise StopIteration
         db = self.__collection.database