README fixes (#42)

Author: juliusgeo

README.rst

@@ -9,7 +9,7 @@ PyMongoExplain
 
 About
 =====
-This package provides an ``ExplainCollection`` class that allows PyMongo's Collection methods to be explained_
+This package provides an ``ExplainableCollection`` class that allows PyMongo's Collection methods to be explained_
 
 PyMongoExplain greatly simplifies the amount of effort needed to explain commands.
 For example, suppose we wanted to explain the following ``update_one``::
@@ -24,7 +24,7 @@ Before PyMongoExplain, one would need to convert the update_one into the equival
 
 After PyMongoExplain::
 
-    ExplainCollection(collection).update_one({"quantity": 1057, "category": "apparel"},{"$set": {"reorder": True}})
+    ExplainableCollection(collection).update_one({"quantity": 1057, "category": "apparel"},{"$set": {"reorder": True}})
 
 .. _explained: https://docs.mongodb.com/master/reference/command/explain/#dbcmd.explain.
 
@@ -38,14 +38,14 @@ To install this package simply use pip::
 Support / Feedback
 ==================
 
-For questions, discussions, or general technical support, visit the MongoDB Community Forums.
+For questions, discussions, or general technical support, visit the `MongoDB Community Forums <https://developer.mongodb.com/community/forums/tag/python>`_.
 The MongoDB Community Forums are a centralized place to connect with other MongoDB users, ask questions, and get answers.
 
 Bugs / Feature Requests
 =======================
 
 Think you’ve found a bug? Want to see a new feature in PyMongoExplain?
-Please open an issue on this GitHub repository.
+Please open an issue on this `GitHub repository <https://github.com/mongodb-labs/pymongoexplain>`_.
 
 How To Ask For Help
 -------------------
@@ -82,14 +82,16 @@ the root of the distribution.
 Tutorial
 ========
 
-PyMongo operations in existing application code can be explained by swapping ``Collection`` objects with ``ExplainCollection``
-objects. The ``ExplainCollection`` class provides all CRUD API methods provided by PyMongo's ``Collection``,
+PyMongo operations in existing application code can be explained by swapping ``Collection`` objects with ``ExplainableCollection``
+objects. The ``ExplainableCollection`` class provides all CRUD API methods provided by PyMongo's ``Collection``,
 but using this class to run operations runs explain on them, instead of executing them.
 
-To run explain on a command, first instantiate an ``ExplainCollection`` from the ``Collection`` object originally used to run the command::
+To run explain on a command, first instantiate an ``ExplainableCollection`` from the ``Collection`` object originally used to run the command::
+
+    from pymongoexplain import ExplainableCollection
 
     collection = client.db.products
-    explain = ExplainCollection(collection)
+    explain = ExplainableCollection(collection)
 
 Now you are ready to explain some commands. Remember that explaining a command does not execute it::
 
@@ -118,7 +120,7 @@ Now ``result`` will contain the output of running explain on the given ``update_
                     'version': '4.4.0-rc13'}}
 
 
-Since ``ExplainCollection`` instances provide all the same methods provided by ``Collection`` instances, explaining operations in your application code is a simple matter of replacing ``Collection`` instances in your application code with ``ExplainCollection`` instances.
+Since ``ExplainableCollection`` instances provide all the same methods provided by ``Collection`` instances, explaining operations in your application code is a simple matter of replacing ``Collection`` instances in your application code with ``ExplainableCollection`` instances.
 
 
 Explaining commands in a script
@@ -134,14 +136,23 @@ within the specified script, **in addition to running every command** in the scr
 explain output is generated using the `logging <https://docs.python.org/3/library/logging.html>`_ module,
 if your script configures logging module there are certain things to keep in mind:
 
-- if your script sets the `logging level <https://docs.python.org/3/library/logging.html#logging-levels>`_
-    higher than INFO, the explain output will be suppressed entirely.
+- if your script sets the `logging level <https://docs.python.org/3/library/logging.html#logging-levels>`_ higher than INFO, the explain output will be suppressed entirely.
 - the explain output will be sent to whatever stream your script configures the logging module to send output to.
 
-
 Any positional parameters or arguments required by your script can be
 simply be appended to the invocation as follows::
 
     python3 -m pymongoexplain <path/to/your/script.py> [PARAMS] [--optname OPTS]
 
 
+Limitations
+-----------
+
+This package does not support the fluent `Cursor API <https://pymongo.readthedocs.io/en/stable/api/pymongo/cursor.html>`_,
+so if you attempt to use it like so::
+
+    ExplainableCollection(collection).find({}).sort(...)
+
+Instead pass all the arguments to the find() call, like so::
+
+    ExplainableCollection(collection).find({}, sort=...)