MOTOR-843 Add support for the comment field to all helpers

motor/docstrings.py

@@ -83,6 +83,10 @@
     :class:`~pymongo.read_concern.ReadConcern`. If ``None`` (the
     default) the :attr:`read_concern` of this :class:`MotorClient` is
     used.
+  - `comment` (optional): A user-provided comment to attach to this command.
+
+.. versionchanged:: 3.0
+   Added ``comment`` parameter.
 
 .. versionadded:: 2.1
    Revived this method. Added the ``default``, ``codec_options``,
@@ -106,12 +110,16 @@
     :meth:`~MotorClient.start_session`.
   - `filter` (optional):  A query document to filter the list of
     collections returned from the listCollections command.
+  - `comment` (optional): A user-provided comment to attach to this command.
   - `**kwargs` (optional): Optional parameters of the
     `listCollections
     <https://www.mongodb.com/docs/manual/reference/command/listCollections/>`_ comand.
     can be passed as keyword arguments to this method. The supported
     options differ by server version.
 
+.. versionchanged:: 3.0
+   Added the ``comment`` parameter.
+
 .. versionchanged:: 2.1
    Added the ``filter`` and ``**kwargs`` parameters.
 
@@ -176,6 +184,7 @@ async def modify_data():
   - `session` (optional): a
     :class:`~pymongo.client_session.ClientSession`, created with
     :meth:`~MotorClient.start_session`.
+  - `comment` (optional): A user-provided comment to attach to this command.
 
 :Returns:
   An instance of :class:`~pymongo.results.BulkWriteResult`.
@@ -185,6 +194,9 @@ async def modify_data():
 .. note:: `bypass_document_validation` requires server version
   **>= 3.2**
 
+.. versionchanged:: 3.0
+   Added comment parameter.
+
 .. versionchanged:: 1.2
    Added session parameter.
 """
@@ -209,12 +221,15 @@ async def create_two_indexes():
   - `session` (optional): a
     :class:`~pymongo.client_session.ClientSession`, created with
     :meth:`~MotorClient.start_session`.
+  - `comment` (optional): A user-provided comment to attach to this command.
   - `**kwargs` (optional): optional arguments to the createIndexes
     command (like maxTimeMS) can be passed as keyword arguments.
 
 The :attr:`~pymongo.collection.Collection.write_concern` of
 this collection is automatically applied to this operation.
 
+.. versionchanged:: 3.0
+   Added comment parameter.
 .. versionchanged:: 1.2
    Added session parameter.
 """
@@ -265,9 +280,13 @@ async def create_two_indexes():
   - `session` (optional): a
     :class:`~pymongo.client_session.ClientSession`, created with
     :meth:`~MotorClient.start_session`.
+  - `comment` (optional): A user-provided comment to attach to this command.
   - `**kwargs` (optional): additional keyword arguments will
     be added to the command document before it is sent
 
+.. versionchanged:: 3.0
+   Added comment parameter.
+
 .. versionchanged:: 1.2
    Added session parameter.
 
@@ -295,10 +314,13 @@ async def clear_collection():
   - `session` (optional): a
     :class:`~pymongo.client_session.ClientSession`, created with
     :meth:`~MotorClient.start_session`.
+  - `comment` (optional): A user-provided comment to attach to this command.
 
 :Returns:
   - An instance of :class:`~pymongo.results.DeleteResult`.
 
+.. versionchanged:: 3.0
+   Added ``comment`` parameter.
 .. versionchanged:: 2.2
    Added ``hint`` parameter.
 .. versionchanged:: 1.2
@@ -326,10 +348,13 @@ async def clear_collection():
   - `session` (optional): a
     :class:`~pymongo.client_session.ClientSession`, created with
     :meth:`~MotorClient.start_session`.
+  - `comment` (optional): A user-provided comment to attach to this command.
 
 :Returns:
   - An instance of :class:`~pymongo.results.DeleteResult`.
 
+.. versionchanged:: 3.0
+   Added ``comment`` parameter.
 .. versionchanged:: 2.2
    Added ``hint`` parameter.
 .. versionchanged:: 1.2
@@ -435,6 +460,7 @@ async def delete_and_return_x():
   - `session` (optional): a
     :class:`~pymongo.client_session.ClientSession`, created with
     :meth:`~MotorClient.start_session`.
+  - `comment` (optional): A user-provided comment to attach to this command.
   - `**kwargs` (optional): additional command arguments can be passed
     as keyword arguments (for example maxTimeMS can be used with
     recent server versions).
@@ -444,6 +470,8 @@ async def delete_and_return_x():
 that using an elevated write concern with this command may be slower compared
 to using the default write concern.
 
+.. versionchanged:: 3.0
+   Added ``comment`` parameter.
 .. versionchanged:: 2.2
    Added ``hint`` parameter.
 .. versionchanged:: 1.2
@@ -507,6 +535,7 @@ async def replace_one_doc():
   - `session` (optional): a
     :class:`~pymongo.client_session.ClientSession`, created with
     :meth:`~MotorClient.start_session`.
+  - `comment` (optional): A user-provided comment to attach to this command.
   - `**kwargs` (optional): additional command arguments can be passed
     as keyword arguments (for example maxTimeMS can be used with
     recent server versions).
@@ -516,6 +545,8 @@ async def replace_one_doc():
 that using an elevated write concern with this command may be slower compared
 to using the default write concern.
 
+.. versionchanged:: 3.0
+   Added ``comment`` parameter.
 .. versionchanged:: 2.2
    Added ``hint`` parameter.
 .. versionchanged:: 1.2
@@ -625,6 +656,7 @@ async def set_done():
   - `session` (optional): a
     :class:`~pymongo.client_session.ClientSession`, created with
     :meth:`~MotorClient.start_session`.
+  - `comment` (optional): A user-provided comment to attach to this command.
   - `**kwargs` (optional): additional command arguments can be passed
     as keyword arguments (for example maxTimeMS can be used with
     recent server versions).
@@ -635,6 +667,8 @@ async def set_done():
 3.2. Note that using an elevated write concern with this command may
 be slower compared to using the default write concern.
 
+.. versionchanged:: 3.0
+   Added ``comment`` parameter.
 .. versionchanged:: 2.2
    Added ``hint`` parameter.
 .. versionchanged:: 1.2
@@ -662,6 +696,9 @@ async def create_x_index():
   {'_id_': {'key': [('_id', 1)]},
    'x_1': {'unique': True, 'key': [('x', 1)]}}
 
+.. versionchanged:: 3.0
+   Added comment parameter.
+
 .. versionchanged:: 1.2
    Added session parameter.
 """
@@ -689,6 +726,7 @@ async def insert_2_docs():
   - `session` (optional): a
     :class:`~pymongo.client_session.ClientSession`, created with
     :meth:`~MotorClient.start_session`.
+  - `comment` (optional): A user-provided comment to attach to this command.
 
 :Returns:
   An instance of :class:`~pymongo.results.InsertManyResult`.
@@ -698,6 +736,9 @@ async def insert_2_docs():
 .. note:: `bypass_document_validation` requires server version
   **>= 3.2**
 
+.. versionchanged:: 3.0
+   Added comment parameter.
+
 .. versionchanged:: 1.2
    Added session parameter.
 """
@@ -722,6 +763,7 @@ async def insert_x():
   - `session` (optional): a
     :class:`~pymongo.client_session.ClientSession`, created with
     :meth:`~MotorClient.start_session`.
+  - `comment` (optional): A user-provided comment to attach to this command.
 
 :Returns:
   - An instance of :class:`~pymongo.results.InsertOneResult`.
@@ -731,6 +773,9 @@ async def insert_x():
 .. note:: `bypass_document_validation` requires server version
   **>= 3.2**
 
+.. versionchanged:: 3.0
+   Added comment parameter.
+
 .. versionchanged:: 1.2
    Added session parameter.
 """
@@ -835,13 +880,16 @@ async def insert_x():
   - `session` (optional): a
     :class:`~pymongo.client_session.ClientSession`, created with
     :meth:`~MotorClient.start_session`.
+  - `comment` (optional): A user-provided comment to attach to this command.
 
 :Returns:
   - An instance of :class:`~pymongo.results.UpdateResult`.
 
 .. note:: `bypass_document_validation` requires server version
   **>= 3.2**
 
+.. versionchanged:: 3.0
+   Added ``comment`` parameter.
 .. versionchanged:: 2.2
    Added ``hint`` parameter.
 .. versionchanged:: 1.2
@@ -895,13 +943,16 @@ async def add_3_to_x():
   - `session` (optional): a
     :class:`~pymongo.client_session.ClientSession`, created with
     :meth:`~MotorClient.start_session`.
+  - `comment` (optional): A user-provided comment to attach to this command.
 
 :Returns:
   - An instance of :class:`~pymongo.results.UpdateResult`.
 
 .. note:: `bypass_document_validation` requires server version
   **>= 3.2**
 
+.. versionchanged:: 3.0
+   Added ``comment`` parameter.
 .. versionchanged:: 2.2
    Added ``hint`` parameter.
 .. versionchanged:: 1.2
@@ -955,13 +1006,16 @@ async def add_3_to_x():
   - `session` (optional): a
     :class:`~pymongo.client_session.ClientSession`, created with
     :meth:`~MotorClient.start_session`.
+  - `comment` (optional): A user-provided comment to attach to this command.
 
 :Returns:
   - An instance of :class:`~pymongo.results.UpdateResult`.
 
 .. note:: `bypass_document_validation` requires server version
   **>= 3.2**
 
+.. versionchanged:: 3.0
+   Added ``comment`` parameter.
 .. versionchanged:: 2.2
    Added ``hint`` parameter.
 .. versionchanged:: 1.2