CDRIVER-3368 Consistent bson_t *reply documentation (#1459)

adriandole · kevinAlbs · web-flow · commit da6db59c9987 · 2024-01-12T13:38:02.000-05:00
More explicit documentation for bson_t out-params. Audit docs to find where bson_t *reply is actually required.

Co-authored-by: Kevin Albertson &lt;kevin.albertson@10gen.com&gt;

---------

Co-authored-by: Kevin Albertson &lt;kevin.albertson@10gen.com&gt;
diff --git a/src/libbson/doc/guides.rst b/src/libbson/doc/guides.rst
@@ -8,3 +8,4 @@ Guides
 
   streaming-bson
   json
+  lifetimes
diff --git a/src/libbson/doc/lifetimes.rst b/src/libbson/doc/lifetimes.rst
@@ -0,0 +1,46 @@
+:man_page: bson_lifetimes
+
+:symbol:`bson_t` lifetimes
+==========================
+A :symbol:`bson_t` may contain its data directly or may contain pointers to heap-allocated memory. Overwriting an existing :symbol:`bson_t`
+or allowing a stack-allocated :symbol:`bson_t` to go out of scope may cause a memory leak. A :symbol:`bson_t` should always be destroyed with
+:symbol:`bson_destroy()`.
+
+:symbol:`bson_t` out parameters
+-------------------------------
+A :symbol:`bson_t` pointer used as an out parameter must point to valid overwritable storage for a new :symbol:`bson_t` which must be one of:
+
+#. Uninitialized storage for a :symbol:`bson_t`.
+#. A zero-initialized :symbol:`bson_t` object.
+#. A :symbol:`bson_t` object initialized with ``BSON_INITIALIZER``.
+#. A :symbol:`bson_t` object not created with :symbol:`bson_new` that was destroyed with :symbol:`bson_destroy`.
+
+This can be on the stack:
+
+.. code-block:: c
+
+  bson_t stack_doc = BSON_INITIALIZER;
+  example_get_doc (&stack_doc);
+  bson_destroy (&stack_doc);
+
+Or on the heap:
+
+.. code-block:: c
+
+  bson_t *heap_doc = bson_malloc (sizeof (bson_t));
+  example_get_doc (heap_doc);
+  bson_destroy (heap_doc);
+  bson_free (heap_doc);
+
+Omitting :symbol:`bson_destroy` in either case may cause memory leaks.
+
+.. warning::
+
+  Passing a :symbol:`bson_t` pointer obtained from :symbol:`bson_new` as an out parameter will result in a leak of the :symbol:`bson_t` struct.
+
+  .. code-block:: c
+
+      bson_t *heap_doc = bson_new ();
+      example_get_doc (heap_doc);
+      bson_destroy (heap_doc); // Leaks the `bson_t` struct!
+      
diff --git a/src/libmongoc/doc/conf.py b/src/libmongoc/doc/conf.py
@@ -187,6 +187,12 @@ def _maybe_update_inventories(app: Sphinx):
 .. |cmcmd:find_package| replace::
     :cmake:command:`find_package() <command:find_package>`
 
+.. |bson_t-storage-ptr| replace::
+    non-``NULL`` pointer to :doc:`overwritable storage <bson:lifetimes>` for a :symbol:`bson_t`
+
+.. |bson_t-opt-storage-ptr| replace::
+    maybe-``NULL`` pointer to :doc:`overwritable storage <bson:lifetimes>` for a :symbol:`bson_t`
+
 """
 
 
diff --git a/src/libmongoc/doc/includes/libbson.inv b/src/libmongoc/doc/includes/libbson.inv
diff --git a/src/libmongoc/doc/mongoc_bulk_operation_execute.rst b/src/libmongoc/doc/mongoc_bulk_operation_execute.rst
@@ -25,7 +25,7 @@ Parameters
 ----------
 
 * ``bulk``: A :symbol:`mongoc_bulk_operation_t`.
-* ``reply``: An uninitialized :symbol:`bson:bson_t`.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 Errors
diff --git a/src/libmongoc/doc/mongoc_client_command_simple.rst b/src/libmongoc/doc/mongoc_client_command_simple.rst
@@ -31,7 +31,7 @@ Parameters
 * ``db_name``: The name of the database to run the command on.
 * ``command``: A :symbol:`bson:bson_t` containing the command specification.
 * ``read_prefs``: An optional :symbol:`mongoc_read_prefs_t`. Otherwise, the command uses mode ``MONGOC_READ_PRIMARY``.
-* ``reply``: A location for the resulting document.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 Errors
diff --git a/src/libmongoc/doc/mongoc_client_command_simple_with_server_id.rst b/src/libmongoc/doc/mongoc_client_command_simple_with_server_id.rst
@@ -29,7 +29,7 @@ Parameters
 * ``db_name``: The name of the database to run the command on.
 * ``read_prefs``: An optional :symbol:`mongoc_read_prefs_t`.
 * ``server_id``: An opaque id specifying which server to use.
-* ``reply``: An optional location for a :symbol:`bson:bson_t` which will store the server's reply.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or a ``NULL``.
 
 Returns
diff --git a/src/libmongoc/doc/mongoc_client_command_with_opts.rst b/src/libmongoc/doc/mongoc_client_command_with_opts.rst
@@ -36,7 +36,7 @@ Parameters
 * ``command``: A :symbol:`bson:bson_t` containing the command specification.
 * ``read_prefs``: An optional :symbol:`mongoc_read_prefs_t`.
 * ``opts``: A :symbol:`bson:bson_t` containing additional options.
-* ``reply``: A location for the resulting document.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. include:: includes/read-write-opts.txt
diff --git a/src/libmongoc/doc/mongoc_client_encryption_delete_key.rst b/src/libmongoc/doc/mongoc_client_encryption_delete_key.rst
@@ -22,7 +22,7 @@ Parameters
 
 * ``client_encryption``: A :symbol:`mongoc_client_encryption_t`.
 * ``keyid``: The UUID (BSON binary subtype 0x04) of the key to delete.
-* ``reply``: Optional. An uninitialized :symbol:`bson:bson_t` set to the delete result. Must be freed by :symbol:`bson_destroy`.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: Optional. :symbol:`bson_error_t`.
 
 Returns
diff --git a/src/libmongoc/doc/mongoc_client_get_server_status.rst b/src/libmongoc/doc/mongoc_client_get_server_status.rst
@@ -30,7 +30,7 @@ Parameters
 
 * ``client``: A :symbol:`mongoc_client_t`.
 * ``read_prefs``: A :symbol:`mongoc_read_prefs_t`.
-* ``reply``: A location for the result :symbol:`bson:bson_t`.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 Errors
diff --git a/src/libmongoc/doc/mongoc_client_read_command_with_opts.rst b/src/libmongoc/doc/mongoc_client_read_command_with_opts.rst
@@ -37,7 +37,7 @@ Parameters
 * ``command``: A :symbol:`bson:bson_t` containing the command specification.
 * ``read_prefs``: An optional :symbol:`mongoc_read_prefs_t`.
 * ``opts``: A :symbol:`bson:bson_t` containing additional options.
-* ``reply``: A location for the resulting document.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. include:: includes/read-opts.txt
diff --git a/src/libmongoc/doc/mongoc_client_read_write_command_with_opts.rst b/src/libmongoc/doc/mongoc_client_read_write_command_with_opts.rst
@@ -36,7 +36,7 @@ Parameters
 * ``command``: A :symbol:`bson:bson_t` containing the command specification.
 * ``read_prefs``: Ignored.
 * ``opts``: A :symbol:`bson:bson_t` containing additional options.
-* ``reply``: A location for the resulting document.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. include:: includes/read-write-opts.txt
diff --git a/src/libmongoc/doc/mongoc_client_session_commit_transaction.rst b/src/libmongoc/doc/mongoc_client_session_commit_transaction.rst
@@ -20,7 +20,7 @@ Parameters
 ----------
 
 * ``session``: A :symbol:`mongoc_client_session_t`.
-* ``reply``: An optional uninitialized :symbol:`bson:bson_t` to receive the server reply, or ``NULL``.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 Return
diff --git a/src/libmongoc/doc/mongoc_client_session_with_transaction.rst b/src/libmongoc/doc/mongoc_client_session_with_transaction.rst
@@ -31,7 +31,7 @@ Parameters
 * ``cb``: A :symbol:`mongoc_client_session_with_transaction_cb_t` callback, which will run inside of a new transaction on the session. See example below.
 * ``opts``: An optional :symbol:`mongoc_transaction_opt_t`.
 * ``ctx``: A ``void*``. This user-provided data will be passed to ``cb``.
-* ``reply``: An optional location to initialize a :symbol:`bson_t` or ``NULL``. This should be on the stack.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t` or ``NULL``.
 
 Return
diff --git a/src/libmongoc/doc/mongoc_client_write_command_with_opts.rst b/src/libmongoc/doc/mongoc_client_write_command_with_opts.rst
@@ -31,7 +31,7 @@ Parameters
 * ``db_name``: The name of the database to run the command on.
 * ``command``: A :symbol:`bson:bson_t` containing the command specification.
 * ``opts``: A :symbol:`bson:bson_t` containing additional options.
-* ``reply``: A location for the resulting document.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. include:: includes/write-opts.txt
diff --git a/src/libmongoc/doc/mongoc_collection_command_simple.rst b/src/libmongoc/doc/mongoc_collection_command_simple.rst
@@ -21,7 +21,7 @@ Parameters
 * ``collection``: A :symbol:`mongoc_collection_t`.
 * ``command``: A :symbol:`bson:bson_t` containing the command to execute.
 * ``read_prefs``: An optional :symbol:`mongoc_read_prefs_t`. Otherwise, the command uses mode ``MONGOC_READ_PRIMARY``.
-* ``reply``: A location to initialize a :symbol:`bson:bson_t`. This should be on the stack.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 Description
diff --git a/src/libmongoc/doc/mongoc_collection_command_with_opts.rst b/src/libmongoc/doc/mongoc_collection_command_with_opts.rst
@@ -32,7 +32,7 @@ Parameters
 * ``command``: A :symbol:`bson:bson_t` containing the command specification.
 * ``read_prefs``: An optional :symbol:`mongoc_read_prefs_t`.
 * ``opts``: A :symbol:`bson:bson_t` containing additional options.
-* ``reply``: A location for the resulting document.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. include:: includes/read-write-opts.txt
diff --git a/src/libmongoc/doc/mongoc_collection_count_documents.rst b/src/libmongoc/doc/mongoc_collection_count_documents.rst
@@ -23,7 +23,7 @@ Parameters
 * ``filter``: A :symbol:`bson:bson_t` containing the filter.
 * ``opts``: A :symbol:`bson:bson_t`, ``NULL`` to ignore.
 * ``read_prefs``: A :symbol:`mongoc_read_prefs_t` or ``NULL``.
-* ``reply``: A location for an uninitialized :symbol:`bson:bson_t` to store the command reply, ``NULL`` to ignore. If not ``NULL``, ``reply`` will be initialized.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. |opts-source| replace:: ``collection``
diff --git a/src/libmongoc/doc/mongoc_collection_create_index_with_opts.rst b/src/libmongoc/doc/mongoc_collection_create_index_with_opts.rst
@@ -28,7 +28,7 @@ Parameters
 * ``collection``: A :symbol:`mongoc_collection_t`.
 * ``keys``: A :symbol:`bson:bson_t`.
 * ``index_opts``: A mongoc_index_opt_t.
-* ``reply``: An optional location for a :symbol:`bson:bson_t` which will store the server's reply.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. |opts-source| replace:: ``collection``
diff --git a/src/libmongoc/doc/mongoc_collection_create_indexes_with_opts.rst b/src/libmongoc/doc/mongoc_collection_create_indexes_with_opts.rst
@@ -30,7 +30,7 @@ Parameters
 * ``models``: An array of ``mongoc_index_model_t *``.
 * ``n_models``: The number of ``models``.
 * ``opts``: Optional options.
-* ``reply``: An optional location for the server reply to the ``createIndexes`` command.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. |opts-source| replace:: ``collection``
diff --git a/src/libmongoc/doc/mongoc_collection_delete_many.rst b/src/libmongoc/doc/mongoc_collection_delete_many.rst
@@ -20,7 +20,7 @@ Parameters
 
 * ``collection``: A :symbol:`mongoc_collection_t`.
 * ``selector``: A :symbol:`bson:bson_t` containing the query to match documents.
-* ``reply``: Optional. An uninitialized :symbol:`bson:bson_t` populated with the delete result, or ``NULL``.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. |opts-source| replace:: ``collection``
diff --git a/src/libmongoc/doc/mongoc_collection_delete_one.rst b/src/libmongoc/doc/mongoc_collection_delete_one.rst
@@ -20,7 +20,7 @@ Parameters
 
 * ``collection``: A :symbol:`mongoc_collection_t`.
 * ``selector``: A :symbol:`bson:bson_t` containing the query to match documents.
-* ``reply``: Optional. An uninitialized :symbol:`bson:bson_t` populated with the delete result, or ``NULL``.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. |opts-source| replace:: ``collection``
diff --git a/src/libmongoc/doc/mongoc_collection_estimated_document_count.rst b/src/libmongoc/doc/mongoc_collection_estimated_document_count.rst
@@ -21,7 +21,7 @@ Parameters
 * ``collection``: A :symbol:`mongoc_collection_t`.
 * ``opts``: A :symbol:`bson:bson_t`, ``NULL`` to ignore.
 * ``read_prefs``: A :symbol:`mongoc_read_prefs_t` or ``NULL``.
-* ``reply``: A location for an uninitialized :symbol:`bson:bson_t` to store the command reply, ``NULL`` to ignore. If not ``NULL``, ``reply`` will be initialized.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. |opts-source| replace:: ``collection``
diff --git a/src/libmongoc/doc/mongoc_collection_find_and_modify.rst b/src/libmongoc/doc/mongoc_collection_find_and_modify.rst
@@ -31,7 +31,7 @@ Parameters
 * ``_remove``: If the matching documents should be removed.
 * ``upsert``: If an upsert should be performed.
 * ``_new``: If the new version of the document should be returned.
-* ``reply``: Optional pointer to an *uninitialized* :symbol:`bson:bson_t` that will be initialized with the result.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 Description
diff --git a/src/libmongoc/doc/mongoc_collection_find_and_modify_with_opts.rst b/src/libmongoc/doc/mongoc_collection_find_and_modify_with_opts.rst
@@ -22,7 +22,7 @@ Parameters
 * ``collection``: A :symbol:`mongoc_collection_t`.
 * ``query``: A :symbol:`bson:bson_t` containing the query to locate target document(s).
 * ``opts``: A :symbol:`find and modify options <mongoc_find_and_modify_opts_t>`. Must not be NULL.
-* ``reply``: An optional location for a :symbol:`bson:bson_t` that will be initialized with the result or ``NULL``.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 Description
diff --git a/src/libmongoc/doc/mongoc_collection_insert_many.rst b/src/libmongoc/doc/mongoc_collection_insert_many.rst
@@ -22,7 +22,7 @@ Parameters
 * ``collection``: A :symbol:`mongoc_collection_t`.
 * ``documents``: An array of pointers to :symbol:`bson:bson_t`.
 * ``n_documents``: The length of ``documents``.
-* ``reply``: Optional. An uninitialized :symbol:`bson:bson_t` populated with the insert result, or ``NULL``.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. |opts-source| replace:: ``collection``
diff --git a/src/libmongoc/doc/mongoc_collection_insert_one.rst b/src/libmongoc/doc/mongoc_collection_insert_one.rst
@@ -20,7 +20,7 @@ Parameters
 
 * ``collection``: A :symbol:`mongoc_collection_t`.
 * ``document``: A :symbol:`bson:bson_t`.
-* ``reply``: Optional. An uninitialized :symbol:`bson:bson_t` populated with the insert result, or ``NULL``.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. |opts-source| replace:: ``collection``
diff --git a/src/libmongoc/doc/mongoc_collection_read_command_with_opts.rst b/src/libmongoc/doc/mongoc_collection_read_command_with_opts.rst
@@ -35,7 +35,7 @@ Parameters
 * ``command``: A :symbol:`bson:bson_t` containing the command specification.
 * ``read_prefs``: An optional :symbol:`mongoc_read_prefs_t`.
 * ``opts``: A :symbol:`bson:bson_t` containing additional options.
-* ``reply``: A location for the resulting document.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. include:: includes/read-opts.txt
diff --git a/src/libmongoc/doc/mongoc_collection_read_write_command_with_opts.rst b/src/libmongoc/doc/mongoc_collection_read_write_command_with_opts.rst
@@ -34,7 +34,7 @@ Parameters
 * ``command``: A :symbol:`bson:bson_t` containing the command specification.
 * ``read_prefs``: Ignored.
 * ``opts``: A :symbol:`bson:bson_t` containing additional options.
-* ``reply``: A location for the resulting document.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. include:: includes/read-write-opts.txt
diff --git a/src/libmongoc/doc/mongoc_collection_replace_one.rst b/src/libmongoc/doc/mongoc_collection_replace_one.rst
@@ -22,7 +22,7 @@ Parameters
 * ``collection``: A :symbol:`mongoc_collection_t`.
 * ``selector``: A :symbol:`bson:bson_t` containing the query to match the document for updating.
 * ``replacement``: A :symbol:`bson:bson_t` containing the replacement document.
-* ``reply``: Optional. An uninitialized :symbol:`bson:bson_t` populated with the update result, or ``NULL``.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. |opts-source| replace:: ``collection``
diff --git a/src/libmongoc/doc/mongoc_collection_stats.rst b/src/libmongoc/doc/mongoc_collection_stats.rst
@@ -24,7 +24,7 @@ Parameters
 
 * ``collection``: A :symbol:`mongoc_collection_t`.
 * ``options``: An optional :symbol:`bson:bson_t` containing extra options to pass to the ``collStats`` command.
-* ``reply``: An uninitialized :symbol:`bson:bson_t` to store the result.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 Description
diff --git a/src/libmongoc/doc/mongoc_collection_update_many.rst b/src/libmongoc/doc/mongoc_collection_update_many.rst
@@ -22,7 +22,7 @@ Parameters
 * ``collection``: A :symbol:`mongoc_collection_t`.
 * ``selector``: A :symbol:`bson:bson_t` containing the query to match documents for updating.
 * ``update``: A :symbol:`bson:bson_t` containing the update to perform. If updating with a pipeline, a :symbol:`bson:bson_t` array.
-* ``reply``: Optional. An uninitialized :symbol:`bson:bson_t` populated with the update result, or ``NULL``.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. |opts-source| replace:: ``collection``
diff --git a/src/libmongoc/doc/mongoc_collection_update_one.rst b/src/libmongoc/doc/mongoc_collection_update_one.rst
@@ -22,7 +22,7 @@ Parameters
 * ``collection``: A :symbol:`mongoc_collection_t`.
 * ``selector``: A :symbol:`bson:bson_t` containing the query to match the document for updating.
 * ``update``: A :symbol:`bson:bson_t` containing the update to perform. If updating with a pipeline, a :symbol:`bson:bson_t` array.
-* ``reply``: Optional. An uninitialized :symbol:`bson:bson_t` populated with the update result, or ``NULL``.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. |opts-source| replace:: ``collection``
diff --git a/src/libmongoc/doc/mongoc_collection_validate.rst b/src/libmongoc/doc/mongoc_collection_validate.rst
@@ -24,7 +24,7 @@ Parameters
 
 * ``collection``: A :symbol:`mongoc_collection_t`.
 * ``options``: A :symbol:`bson:bson_t`.
-* ``reply``: An optional location for a :symbol:`bson:bson_t`.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 Description
diff --git a/src/libmongoc/doc/mongoc_collection_write_command_with_opts.rst b/src/libmongoc/doc/mongoc_collection_write_command_with_opts.rst
@@ -29,7 +29,7 @@ Parameters
 * ``collection``: A :symbol:`mongoc_collection_t`.
 * ``command``: A :symbol:`bson:bson_t` containing the command specification.
 * ``opts``: A :symbol:`bson:bson_t` containing additional options.
-* ``reply``: A location for the resulting document.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. include:: includes/write-opts.txt
diff --git a/src/libmongoc/doc/mongoc_database_command_simple.rst b/src/libmongoc/doc/mongoc_database_command_simple.rst
@@ -21,7 +21,7 @@ Parameters
 * ``database``: A :symbol:`mongoc_database_t`.
 * ``command``: A :symbol:`bson:bson_t` containing the command.
 * ``read_prefs``: An optional :symbol:`mongoc_read_prefs_t`. Otherwise, the command uses mode ``MONGOC_READ_PRIMARY``.
-* ``reply``: A location to store the commands first result document.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 This is a simplified interface to :symbol:`mongoc_database_command()` that returns the first result document. The database's read preference, read concern, and write concern are not applied to the command.  The parameter ``reply`` is initialized even upon failure to simplify memory management.
diff --git a/src/libmongoc/doc/mongoc_database_command_with_opts.rst b/src/libmongoc/doc/mongoc_database_command_with_opts.rst
@@ -34,7 +34,7 @@ Parameters
 * ``command``: A :symbol:`bson:bson_t` containing the command specification.
 * ``read_prefs``: An optional :symbol:`mongoc_read_prefs_t`.
 * ``opts``: A :symbol:`bson:bson_t` containing additional options.
-* ``reply``: A location for the resulting document.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. include:: includes/read-write-opts.txt
diff --git a/src/libmongoc/doc/mongoc_database_read_command_with_opts.rst b/src/libmongoc/doc/mongoc_database_read_command_with_opts.rst
@@ -35,7 +35,7 @@ Parameters
 * ``command``: A :symbol:`bson:bson_t` containing the command specification.
 * ``read_prefs``: An optional :symbol:`mongoc_read_prefs_t`.
 * ``opts``: A :symbol:`bson:bson_t` containing additional options.
-* ``reply``: A location for the resulting document.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. include:: includes/read-opts.txt
diff --git a/src/libmongoc/doc/mongoc_database_read_write_command_with_opts.rst b/src/libmongoc/doc/mongoc_database_read_write_command_with_opts.rst
@@ -34,7 +34,7 @@ Parameters
 * ``command``: A :symbol:`bson:bson_t` containing the command specification.
 * ``read_prefs``: Ignored.
 * ``opts``: A :symbol:`bson:bson_t` containing additional options.
-* ``reply``: A location for the resulting document.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. include:: includes/read-write-opts.txt
diff --git a/src/libmongoc/doc/mongoc_database_write_command_with_opts.rst b/src/libmongoc/doc/mongoc_database_write_command_with_opts.rst
@@ -30,7 +30,7 @@ Parameters
 * ``db_name``: The name of the database to run the command on.
 * ``command``: A :symbol:`bson:bson_t` containing the command specification.
 * ``opts``: A :symbol:`bson:bson_t` containing additional options.
-* ``reply``: A location for the resulting document.
+* ``reply``: A |bson_t-opt-storage-ptr| to contain the results.
 * ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
 
 .. include:: includes/write-opts.txt
diff --git a/src/libmongoc/doc/mongoc_error_has_label.rst b/src/libmongoc/doc/mongoc_error_has_label.rst
@@ -16,7 +16,7 @@ Test whether a reply from a failed operation includes a specific error label. Se
 Parameters
 ----------
 
-* ``reply``: A :symbol:`bson:bson_t`, the reply to a failed operation.
+* ``reply``: A |bson_t-storage-ptr| to contain the results.
 * ``label``: The label to test for, such as "TransientTransactionError" or "UnknownTransactionCommitResult".
 
 Returns
