Improve docs of cursor returning functions (#740)

Co-authored-by: Kevin Albertson <[email protected]>
Co-authored-by: Fermín Galán Márquez <[email protected]>

Author: fgalan

src/libmongoc/doc/includes/returns-cursor.txt

@@ -0,0 +1,7 @@
+This function returns a newly allocated :symbol:`mongoc_cursor_t` that should be freed with :symbol:`mongoc_cursor_destroy()` when no longer in use. The returned :symbol:`mongoc_cursor_t` is never ``NULL``, even on error. The user must call :symbol:`mongoc_cursor_next()` on the returned :symbol:`mongoc_cursor_t` to execute the initial command.
+
+Cursor errors can be checked with :symbol:`mongoc_cursor_error_document`. It always fills out the :symbol:`bson_error_t` if an error occurred, and optionally includes a server reply document if the error occurred server-side.
+
+.. warning::
+
+  Failure to handle the result of this function is a programming error.

src/libmongoc/doc/mongoc_collection_aggregate.rst

@@ -54,11 +54,7 @@ Transaction        Transaction    Transaction
 Returns
 -------
 
-This function returns a newly allocated :symbol:`mongoc_cursor_t` that should be freed with :symbol:`mongoc_cursor_destroy()` when no longer in use. The returned :symbol:`mongoc_cursor_t` is never ``NULL``; if the parameters are invalid, the :symbol:`bson:bson_error_t` in the :symbol:`mongoc_cursor_t` is filled out, and the :symbol:`mongoc_cursor_t` is returned before the server is selected. The user must call :symbol:`mongoc_cursor_next()` on the returned :symbol:`mongoc_cursor_t` to execute the aggregation pipeline.
-
-.. warning::
-
-  Failure to handle the result of this function is a programming error.
+.. include:: includes/returns-cursor.txt
 
 Example
 -------

src/libmongoc/doc/mongoc_collection_command.rst

@@ -38,7 +38,4 @@ Parameters
 Returns
 -------
 
-A :symbol:`mongoc_cursor_t`.
-
-The cursor should be freed with :symbol:`mongoc_cursor_destroy()`.
-
+.. include:: includes/returns-cursor.txt

src/libmongoc/doc/mongoc_collection_find.rst

@@ -51,7 +51,7 @@ If no options are necessary, ``query`` can simply contain a query such as ``{a:1
 Returns
 -------
 
-A newly allocated :symbol:`mongoc_cursor_t` that should be freed with :symbol:`mongoc_cursor_destroy()` when no longer in use.
+.. include:: includes/returns-cursor.txt
 
 Example
 -------

src/libmongoc/doc/mongoc_collection_find_indexes.rst

@@ -37,4 +37,9 @@ Errors are propagated via the ``error`` parameter.
 Returns
 -------
 
-A cursor where each result corresponds to the server's representation of an index on this collection. If the collection does not exist on the server, the cursor will be empty.
+.. include:: includes/returns-cursor.txt
+
+In the returned cursor each result corresponds to the server's representation of an index on this collection. If the collection does not exist on the server, the cursor will be empty.
+
+The cursor functions :symbol:`mongoc_cursor_set_limit`, :symbol:`mongoc_cursor_set_batch_size`, and :symbol:`mongoc_cursor_set_max_await_time_ms` have no use on the returned cursor.
+

src/libmongoc/doc/mongoc_collection_find_indexes_with_opts.rst

@@ -34,7 +34,9 @@ Use :symbol:`mongoc_cursor_error` on the returned cursor to check for errors.
 Returns
 -------
 
-A cursor where each result corresponds to the server's representation of an index on this collection. If the collection does not exist on the server, the cursor will be empty.
+.. include:: includes/returns-cursor.txt
+
+In the returned cursor each result corresponds to the server's representation of an index on this collection. If the collection does not exist on the server, the cursor will be empty.
 
 The cursor functions :symbol:`mongoc_cursor_set_limit`, :symbol:`mongoc_cursor_set_batch_size`, and :symbol:`mongoc_cursor_set_max_await_time_ms` have no use on the returned cursor.
 

src/libmongoc/doc/mongoc_collection_find_with_opts.rst

@@ -39,7 +39,7 @@ To target a specific server, include an integer "serverId" field in ``opts`` wit
 Returns
 -------
 
-A newly allocated :symbol:`mongoc_cursor_t` that must be freed with :symbol:`mongoc_cursor_destroy()`.
+.. include:: includes/returns-cursor.txt
 
 Examples
 --------

src/libmongoc/doc/mongoc_database_aggregate.rst

@@ -51,11 +51,7 @@ Transaction        Transaction    Transaction
 Returns
 -------
 
-This function returns a newly allocated :symbol:`mongoc_cursor_t` that should be freed with :symbol:`mongoc_cursor_destroy()` when no longer in use. The returned :symbol:`mongoc_cursor_t` is never ``NULL``; if the parameters are invalid, the :symbol:`bson:bson_error_t` in the :symbol:`mongoc_cursor_t` is filled out, and the :symbol:`mongoc_cursor_t` is returned before the server is selected. The user must call :symbol:`mongoc_cursor_next()` on the returned :symbol:`mongoc_cursor_t` to execute the aggregation pipeline.
-
-.. warning::
-
-  Failure to handle the result of this function is a programming error.
+.. include:: includes/returns-cursor.txt
 
 Example
 -------

src/libmongoc/doc/mongoc_database_command.rst

@@ -42,7 +42,5 @@ Parameters
 Returns
 -------
 
-A :symbol:`mongoc_cursor_t`.
-
-The cursor should be freed with :symbol:`mongoc_cursor_destroy()`.
+.. include:: includes/returns-cursor.txt
 

src/libmongoc/doc/mongoc_database_find_collections.rst

@@ -43,5 +43,8 @@ Errors are propagated via the ``error`` parameter.
 Returns
 -------
 
-A cursor where each result corresponds to the server's representation of a collection in this database.
+This function returns a newly allocated :symbol:`mongoc_cursor_t` that should be freed with :symbol:`mongoc_cursor_destroy()` when no longer in use, or `NULL` in case of error. The user must call :symbol:`mongoc_cursor_next()` on the returned :symbol:`mongoc_cursor_t` to execute the initial command.
 
+In the returned cursor each result corresponds to the server's representation of a collection in this database.
+
+The cursor functions :symbol:`mongoc_cursor_set_limit`, :symbol:`mongoc_cursor_set_batch_size`, and :symbol:`mongoc_cursor_set_max_await_time_ms` have no use on the returned cursor.

src/libmongoc/doc/mongoc_database_find_collections_with_opts.rst

@@ -38,7 +38,9 @@ Use :symbol:`mongoc_cursor_error` on the returned cursor to check for errors.
 Returns
 -------
 
-A cursor where each result corresponds to the server's representation of a collection in this database.
+.. include:: includes/returns-cursor.txt
+
+In the returned cursor each result corresponds to the server's representation of a collection in this database.
 
 The cursor functions :symbol:`mongoc_cursor_set_limit`, :symbol:`mongoc_cursor_set_batch_size`, and :symbol:`mongoc_cursor_set_max_await_time_ms` have no use on the returned cursor.