CDRIVER-4363 document mongoc_bulkwrite_t (#1602)

* document `mongoc_bulkwrite_t`

* rename `set_hint_opt` to `set_bson_value_opt`

To reuse for the `comment` option

* use `bson_value_t` for `comment`, not `bson_t`

Matches the spec, and existing C driver representation of `comment` for other functions.

---------

Co-authored-by: Roberto C. Sánchez <[email protected]>

Author: kevinAlbs

CONTRIBUTING.md

@@ -127,6 +127,12 @@ documentation to be generated:
 ./tools/poetry.sh run sphinx-build -WEn -bhtml src/libmongoc/doc/ src/libmongoc/doc/html
 ```
 
+`sphinx-autobuild` can be used to serve docs locally. This can be convenient when editing. Files are rebuilt
+when changes are detected:
+
+```sh
+./tools/poetry.sh run sphinx-autobuild -b html src/libmongoc/doc/ src/libmongoc/doc/html --re-ignore ".*.pickle" --re-ignore ".*.doctree" -j auto
+```
 
 ### Testing
 

src/libmongoc/doc/api.rst

@@ -11,6 +11,10 @@ API Reference
    lifecycle
    gridfs
    mongoc_auto_encryption_opts_t
+   mongoc_bulkwrite_t
+   mongoc_bulkwriteopts_t
+   mongoc_bulkwriteresult_t
+   mongoc_bulkwriteexception_t
    mongoc_bulk_operation_t
    mongoc_change_stream_t
    mongoc_client_encryption_t

src/libmongoc/doc/includes/bulkwrite-vs-bulk_operation.txt

@@ -0,0 +1,10 @@
+If using MongoDB server 8.0+, prefer :symbol:`mongoc_bulkwrite_t` over :symbol:`mongoc_bulk_operation_t` to reduce
+network round trips.
+
+:symbol:`mongoc_bulkwrite_t` uses the ``bulkWrite`` server command introduced in MongoDB server 8.0. ``bulkWrite``
+command supports insert, update, and delete operations in the same payload. ``bulkWrite`` supports use of multiple
+collection namespaces in the same payload.
+
+:symbol:`mongoc_bulk_operation_t` uses the ``insert``, ``update`` and ``delete`` server commands available in all
+current MongoDB server versions. Write operations are grouped by type (insert, update, delete) and sent in separate
+commands. Only one collection may be specified per bulk write.

src/libmongoc/doc/mongoc_bulk_operation_t.rst

@@ -12,9 +12,13 @@ Synopsis
 
   typedef struct _mongoc_bulk_operation_t mongoc_bulk_operation_t;
 
-The opaque type ``mongoc_bulk_operation_t`` provides an abstraction for submitting multiple write operations as a single batch.
+Description
+-----------
 
-After adding all of the write operations to the ``mongoc_bulk_operation_t``, call :symbol:`mongoc_bulk_operation_execute()` to execute the operation.
+:symbol:`mongoc_bulk_operation_t` provides an abstraction for submitting multiple write operations as a single batch.
+
+After adding all of the write operations to the :symbol:`mongoc_bulk_operation_t`, call
+:symbol:`mongoc_bulk_operation_execute()` to execute the operation.
 
 .. warning::
 
@@ -23,6 +27,11 @@ After adding all of the write operations to the ``mongoc_bulk_operation_t``, cal
 .. seealso::
 
   | `Bulk Write Operations <bulk_>`_
+  | :symbol:`mongoc_bulkwrite_t`
+
+.. note::
+
+  .. include:: includes/bulkwrite-vs-bulk_operation.txt
 
 .. only:: html
 

src/libmongoc/doc/mongoc_bulkwrite_append_deletemany.rst

@@ -0,0 +1,22 @@
+:man_page: mongoc_bulkwrite_append_deletemany
+
+mongoc_bulkwrite_append_deletemany()
+====================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   bool
+   mongoc_bulkwrite_append_deletemany (mongoc_bulkwrite_t *self,
+                                       const char *ns,
+                                       const bson_t *filter,
+                                       const mongoc_bulkwrite_deletemanyopts_t *opts /* May be NULL */,
+                                       bson_error_t *error);
+
+Description
+-----------
+
+Adds a multi-document delete into the namespace ``ns``. Returns true on success. Returns false and sets ``error`` if an
+error occured.

src/libmongoc/doc/mongoc_bulkwrite_append_deleteone.rst

@@ -0,0 +1,22 @@
+:man_page: mongoc_bulkwrite_append_deleteone
+
+mongoc_bulkwrite_append_deleteone()
+===================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   bool
+   mongoc_bulkwrite_append_deleteone (mongoc_bulkwrite_t *self,
+                                      const char *ns,
+                                      const bson_t *filter,
+                                      const mongoc_bulkwrite_deleteoneopts_t *opts /* May be NULL */,
+                                      bson_error_t *error);
+
+Description
+-----------
+
+Adds a single-document delete into the namespace ``ns``. Returns true on success. Returns false and sets ``error`` if an
+error occured.

src/libmongoc/doc/mongoc_bulkwrite_append_insertone.rst

@@ -0,0 +1,22 @@
+:man_page: mongoc_bulkwrite_append_insertone
+
+mongoc_bulkwrite_append_insertone()
+===================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   bool
+   mongoc_bulkwrite_append_insertone (mongoc_bulkwrite_t *self,
+                                      const char *ns,
+                                      const bson_t *document,
+                                      const mongoc_bulkwrite_insertoneopts_t *opts /* May be NULL */,
+                                      bson_error_t *error);
+
+Description
+-----------
+
+Adds a document to insert into the namespace ``ns``. Returns true on success. Returns false and sets ``error`` if an
+error occured.

src/libmongoc/doc/mongoc_bulkwrite_append_replaceone.rst

@@ -0,0 +1,23 @@
+:man_page: mongoc_bulkwrite_append_replaceone
+
+mongoc_bulkwrite_append_replaceone()
+====================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   bool
+   mongoc_bulkwrite_append_replaceone (mongoc_bulkwrite_t *self,
+                                       const char *ns,
+                                       const bson_t *filter,
+                                       const bson_t *replacement,
+                                       const mongoc_bulkwrite_replaceoneopts_t *opts /* May be NULL */,
+                                       bson_error_t *error);
+
+Description
+-----------
+
+Adds a replace operation for the namespace ``ns``. Returns true on success. Returns false and sets ``error`` if an
+error occured.

src/libmongoc/doc/mongoc_bulkwrite_append_updatemany.rst

@@ -0,0 +1,23 @@
+:man_page: mongoc_bulkwrite_append_updatemany
+
+mongoc_bulkwrite_append_updatemany()
+====================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   bool
+   mongoc_bulkwrite_append_updatemany (mongoc_bulkwrite_t *self,
+                                       const char *ns,
+                                       const bson_t *filter,
+                                       const bson_t *update,
+                                       const mongoc_bulkwrite_updatemanyopts_t *opts /* May be NULL */,
+                                       bson_error_t *error);
+
+Description
+-----------
+
+Adds a multi-document update for the namespace ``ns``. Returns true on success. Returns false and sets ``error`` if an
+error occured.

src/libmongoc/doc/mongoc_bulkwrite_append_updateone.rst

@@ -0,0 +1,23 @@
+:man_page: mongoc_bulkwrite_append_updateone
+
+mongoc_bulkwrite_append_updateone()
+===================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   bool
+   mongoc_bulkwrite_append_updateone (mongoc_bulkwrite_t *self,
+                                      const char *ns,
+                                      const bson_t *filter,
+                                      const bson_t *update,
+                                      const mongoc_bulkwrite_updateoneopts_t *opts /* May be NULL */,
+                                      bson_error_t *error);
+
+Description
+-----------
+
+Adds a single-document update for the namespace ``ns``. Returns true on success. Returns false and sets ``error`` if an
+error occured.

src/libmongoc/doc/mongoc_bulkwrite_deletemanyopts_destroy.rst

@@ -0,0 +1,17 @@
+:man_page: mongoc_bulkwrite_deletemanyopts_destroy
+
+mongoc_bulkwrite_deletemanyopts_destroy()
+=========================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   void
+   mongoc_bulkwrite_deletemanyopts_destroy (mongoc_bulkwrite_deletemanyopts_t *self);
+
+Description
+-----------
+
+Frees a :symbol:`mongoc_bulkwrite_deletemanyopts_t`.

src/libmongoc/doc/mongoc_bulkwrite_deletemanyopts_new.rst

@@ -0,0 +1,17 @@
+:man_page: mongoc_bulkwrite_deletemanyopts_new
+
+mongoc_bulkwrite_deletemanyopts_new()
+=====================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   mongoc_bulkwrite_deletemanyopts_t *
+   mongoc_bulkwrite_deletemanyopts_new (void);
+
+Description
+-----------
+
+Returns a new :symbol:`mongoc_bulkwrite_deletemanyopts_new`.

src/libmongoc/doc/mongoc_bulkwrite_deletemanyopts_set_collation.rst

@@ -0,0 +1,17 @@
+:man_page: mongoc_bulkwrite_deletemanyopts_set_collation
+
+mongoc_bulkwrite_deletemanyopts_set_collation()
+===============================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   void
+   mongoc_bulkwrite_deletemanyopts_set_collation (mongoc_bulkwrite_deletemanyopts_t *self, const bson_t *collation);
+
+Description
+-----------
+
+Specifies a collation.

src/libmongoc/doc/mongoc_bulkwrite_deletemanyopts_set_hint.rst

@@ -0,0 +1,18 @@
+:man_page: mongoc_bulkwrite_deletemanyopts_set_hint
+
+mongoc_bulkwrite_deletemanyopts_set_hint()
+==========================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   void
+   mongoc_bulkwrite_deletemanyopts_set_hint (mongoc_bulkwrite_deletemanyopts_t *self, const bson_value_t *hint);
+
+Description
+-----------
+
+Specifies the index to use. Specify either the index name as a string or the index key pattern. If specified, then the
+query system will only consider plans using the hinted index.

src/libmongoc/doc/mongoc_bulkwrite_deletemanyopts_t.rst

@@ -0,0 +1,25 @@
+:man_page: mongoc_bulkwrite_deletemanyopts_t
+
+mongoc_bulkwrite_deletemanyopts_t
+=================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  typedef struct _mongoc_bulkwrite_deletemanyopts_t mongoc_bulkwrite_deletemanyopts_t;
+
+.. only:: html
+
+  Functions
+  ---------
+
+  .. toctree::
+    :titlesonly:
+    :maxdepth: 1
+
+    mongoc_bulkwrite_deletemanyopts_new
+    mongoc_bulkwrite_deletemanyopts_destroy
+    mongoc_bulkwrite_deletemanyopts_set_collation
+    mongoc_bulkwrite_deletemanyopts_set_hint

src/libmongoc/doc/mongoc_bulkwrite_deleteoneopts_destroy.rst

@@ -0,0 +1,17 @@
+:man_page: mongoc_bulkwrite_deleteoneopts_destroy
+
+mongoc_bulkwrite_deleteoneopts_destroy()
+========================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   void
+   mongoc_bulkwrite_deleteoneopts_destroy (mongoc_bulkwrite_deleteoneopts_t *self);
+
+Description
+-----------
+
+Frees a :symbol:`mongoc_bulkwrite_deleteoneopts_t`.

src/libmongoc/doc/mongoc_bulkwrite_deleteoneopts_new.rst

@@ -0,0 +1,17 @@
+:man_page: mongoc_bulkwrite_deleteoneopts_new
+
+mongoc_bulkwrite_deleteoneopts_new()
+====================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   mongoc_bulkwrite_deleteoneopts_t *
+   mongoc_bulkwrite_deleteoneopts_new (void);
+
+Description
+-----------
+
+Returns a new :symbol:`mongoc_bulkwrite_deleteoneopts_t`.

src/libmongoc/doc/mongoc_bulkwrite_deleteoneopts_set_collation.rst

@@ -0,0 +1,17 @@
+:man_page: mongoc_bulkwrite_deleteoneopts_set_collation
+
+mongoc_bulkwrite_deleteoneopts_set_collation()
+==============================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   void
+   mongoc_bulkwrite_deleteoneopts_set_collation (mongoc_bulkwrite_deleteoneopts_t *self, const bson_t *collation);
+
+Description
+-----------
+
+Specifies a collation.

src/libmongoc/doc/mongoc_bulkwrite_deleteoneopts_set_hint.rst

@@ -0,0 +1,18 @@
+:man_page: mongoc_bulkwrite_deleteoneopts_set_hint
+
+mongoc_bulkwrite_deleteoneopts_set_hint()
+=========================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   void
+   mongoc_bulkwrite_deleteoneopts_set_hint (mongoc_bulkwrite_deleteoneopts_t *self, const bson_value_t *hint);
+
+Description
+-----------
+
+Specifies the index to use. Specify either the index name as a string or the index key pattern. If specified, then the
+query system will only consider plans using the hinted index.