Add documentation for mongoc_optional_t

Author: alcaeus

src/libmongoc/doc/api.rst

@@ -38,6 +38,7 @@ API Reference
    mongoc_insert_flags_t
    mongoc_iovec_t
    mongoc_matcher_t
+   mongoc_optional_t
    mongoc_query_flags_t
    mongoc_rand
    mongoc_read_concern_t

src/libmongoc/doc/mongoc_optional_copy.rst

@@ -0,0 +1,20 @@
+:man_page: mongoc_optional_copy
+
+mongoc_optional_copy()
+======================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  mongoc_optional_t *
+  mongoc_optional_copy (const mongoc_optional_t *source, mongoc_optional_t *copy);
+
+Creates a deep copy of ``source`` into ``copy``.
+
+Parameters
+----------
+
+* ``source``: A :symbol:`mongoc_optional_t`.
+* ``copy``: An empty :symbol:`mongoc_optional_t`. Values will be overwritten.

src/libmongoc/doc/mongoc_optional_init.rst

@@ -0,0 +1,19 @@
+:man_page: mongoc_optional_init
+
+mongoc_optional_init()
+======================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  void
+  mongoc_optional_init (mongoc_optional_t *opt);
+
+Initializes values for a :symbol:`mongoc_optional_t`.
+
+Parameters
+----------
+
+* ``opt``: A :symbol:`mongoc_optional_t`.

src/libmongoc/doc/mongoc_optional_is_set.rst

@@ -0,0 +1,24 @@
+:man_page: mongoc_optional_is_set
+
+mongoc_optional_is_set()
+========================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  bool
+  mongoc_optional_is_set (const mongoc_optional_t *opt);
+
+Returns whether a value for a :symbol:`mongoc_optional_t` was set.
+
+Parameters
+----------
+
+* ``opt``: A :symbol:`mongoc_optional_t`.
+
+Returns
+-------
+
+Returns ``true`` if a value was set, or ``false`` otherwise.

src/libmongoc/doc/mongoc_optional_set_value.rst

@@ -0,0 +1,19 @@
+:man_page: mongoc_optional_set_value
+
+mongoc_optional_set_value()
+===========================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  void
+  mongoc_optional_set_value (mongoc_optional_t *opt);
+
+Sets a value on a :symbol:`mongoc_optional_t`. Once a value has been set, it cannot be unset, i.e. `mongoc_optional_is_set` will always return ``true`` after calling `mongoc_optional_set_value`.
+
+Parameters
+----------
+
+* ``opt``: A :symbol:`mongoc_optional_t`.

src/libmongoc/doc/mongoc_optional_t.rst

@@ -0,0 +1,28 @@
+:man_page: mongoc_optional_t
+
+mongoc_optional_t
+=================
+
+A struct to store optional boolean values.
+
+Synopsis
+--------
+
+Used to specify optional boolean flags, which may remain unset.
+
+This is used within :symbol:`mongoc_server_api_t` to track whether a flag was explicitly set.
+
+.. only:: html
+
+  Functions
+  ---------
+
+  .. toctree::
+    :titlesonly:
+    :maxdepth: 1
+
+    mongoc_optional_copy
+    mongoc_optional_init
+    mongoc_optional_is_set
+    mongoc_optional_set_value
+    mongoc_optional_value

src/libmongoc/doc/mongoc_optional_value.rst

@@ -0,0 +1,24 @@
+:man_page: mongoc_optional_value
+
+mongoc_optional_value()
+=======================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  bool
+  mongoc_optional_value (const mongoc_optional_t *opt);
+
+Returns the value for a :symbol:`mongoc_optional_t`.
+
+Parameters
+----------
+
+* ``opt``: A :symbol:`mongoc_optional_t`.
+
+Returns
+-------
+
+Returns the value that was set on the :symbol:`mongoc_optional_t`. If no value was set, ``false`` is returned.