C Docs Migration: format edits (#1)

* Libbson and libmongoc

* More format edits

* rest of libbson files

* libmongoc formatting

* directive issues

* more libbson fixes

* add example folder

Author: norareidy

source/docs-libbson/.gitignore

@@ -0,0 +1,14 @@
+*.7
+*.pyc
+.doctrees
+objects.inv
+html/*.html
+html/*.css
+html/*.js
+html/*.png
+html/_sources
+html/_static
+html/.buildinfo
+html/.nojekyll
+man/*.3
+man/.buildinfo

source/docs-libbson/CMakeLists.txt

@@ -0,0 +1,9 @@
+include (SphinxBuild)
+
+if (ENABLE_HTML_DOCS)
+   sphinx_build_html (bson-html libbson)
+endif ()
+
+if (ENABLE_MAN_PAGES)
+   sphinx_build_man (bson-man)
+endif ()

source/docs-libbson/api.txt

@@ -0,0 +1,28 @@
+=============
+API Reference
+=============
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 2
+
+   bson_t
+   bson_array_builder_t
+   bson_context_t
+   bson_decimal128_t
+   bson_error_t
+   bson_iter_t
+   bson_json_reader_t
+   bson_oid_t
+   bson_reader_t
+   character_and_string_routines
+   bson_string_t
+   bson_subtype_t
+   bson_type_t
+   bson_unichar_t
+   bson_value_t
+   bson_visitor_t
+   bson_writer_t
+   bson_get_monotonic_time
+   bson_memory
+   version

source/docs-libbson/bson_aligned_alloc.txt

@@ -0,0 +1,39 @@
+.. _bson_aligned_alloc:
+
+====================
+bson_aligned_alloc()
+====================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  void *
+  bson_aligned_alloc (size_t alignment, size_t num_bytes);
+
+Parameters
+----------
+
+- ``alignment``: The alignment of the allocated bytes of memory. Must be a power of 2 and a multiple
+  of ``sizeof (void *)``.
+- ``num_bytes``: The number of bytes to allocate. Must be a multiple of ``alignment``.
+
+Description
+-----------
+
+This is a portable ``aligned_alloc()`` wrapper.
+
+In general, this function will return an allocation at least ``sizeof(void*)`` bytes or bigger with an
+alignment of at least ``alignment``.
+
+If there was a failure to allocate ``num_bytes`` bytes aligned to ``alignment``, the process will be aborted.
+
+.. warning::
+
+  This function will abort on failure to allocate memory.
+
+Returns
+-------
+
+A pointer to a memory region which *HAS NOT* been zeroed.

source/docs-libbson/bson_aligned_alloc0.txt

@@ -0,0 +1,40 @@
+.. _bson_aligned_alloc0:
+
+=====================
+bson_aligned_alloc0()
+=====================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   void *
+   bson_aligned_alloc0 (size_t alignment, size_t num_bytes);
+
+Parameters
+----------
+
+- ``alignment``: The alignment of the allocated bytes of memory. Must be a power of 2 and
+  a multiple of ``sizeof (void *)``.
+- ``num_bytes``: The number of bytes to allocate. Must be a multiple of ``alignment``.
+
+Description
+-----------
+
+This is a portable ``aligned_alloc()`` wrapper that also sets the memory to zero.
+
+In general, this function will return an allocation at least ``sizeof(void*)`` bytes or bigger with
+an alignment of at least ``alignment``.
+
+If there was a failure to allocate ``num_bytes`` bytes aligned to ``alignment``, the process will
+be aborted.
+
+.. warning::
+
+   This function will abort on failure to allocate memory.
+
+Returns
+-------
+
+A pointer to a memory region which *HAS* been zeroed.

source/docs-libbson/bson_append_array.txt

@@ -0,0 +1,44 @@
+.. _bson_append_array:
+
+===================
+bson_append_array()
+===================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   #define BSON_APPEND_ARRAY(b, key, val) \
+      bson_append_array (b, key, (int) strlen (key), val)
+
+   bool
+   bson_append_array (bson_t *bson,
+                      const char *key,
+                      int key_length,
+                      const bson_t *array);
+
+Parameters
+----------
+
+- ``bson``: A :ref:`bson_t`.
+- ``key``: An ASCII C string containing the name of the field.
+- ``key_length``: The length of ``key`` in bytes, or -1 to determine the length with ``strlen()``.
+- ``array``: A :ref:`bson_t`.
+
+Description
+-----------
+
+The :ref:`bson_append_array()` function shall append ``array`` to ``bson`` using the specified
+key. The type of the field will be an array, but it is the responsibility of the caller to ensure
+that the keys of ``array`` are properly formatted with string keys such as "0", "1", "2" and so forth.
+
+Returns
+-------
+
+Returns ``true`` if the operation was applied successfully. The function fails if appending the array
+grows ``bson`` larger than INT32_MAX.
+
+.. seealso::
+
+   | :ref:`bson_array_builder_t`

source/docs-libbson/bson_append_array_begin.txt

@@ -0,0 +1,51 @@
+.. _bson_append_array_begin:
+
+=========================
+bson_append_array_begin()
+=========================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   #define BSON_APPEND_ARRAY_BEGIN(b, key, child) \
+      bson_append_array_begin (b, key, (int) strlen (key), child)
+
+   bool
+   bson_append_array_begin (bson_t *bson,
+                            const char *key,
+                            int key_length,
+                            bson_t *child);
+
+Parameters
+----------
+
+- ``bson``: A :ref:`bson_t`.
+- ``key``: A string containing the name for the key.
+- ``key_length``: The length of ``key`` or -1 to call ``strlen()``.
+- ``child``: A :ref:`bson_t`.
+
+Description
+-----------
+
+The :ref:`bson_append_array_begin` function shall begin appending an array field to
+``bson``. This allows for incrementally building a sub-array. Doing so will generally yield
+better performance as you will serialize to a single buffer. When done building the sub-array,
+the caller *MUST* call :ref:`bson_append_array_end`.
+
+For generating array element keys, see :ref:`bson_uint32_to_string`.
+
+Consider using :ref:`bson_array_builder_t` to append an array without needing to generate
+array element keys.
+
+Returns
+-------
+
+Returns ``true`` if the operation was applied successfully. The function will fail if appending
+the array grows ``bson`` larger than INT32_MAX.
+
+.. seealso::
+
+   | :ref:`bson_array_builder_t`
+

source/docs-libbson/bson_append_array_end.txt

@@ -0,0 +1,34 @@
+.. _bson_append_array_end:
+
+=======================
+bson_append_array_end()
+=======================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   bool
+   bson_append_array_end (bson_t *bson, bson_t *child);
+
+Parameters
+----------
+
+- ``bson``: A :ref:`bson_t`.
+- ``child``: The :ref:`bson_t` initialized in a call to :ref:`bson_append_array_begin()`.
+
+Description
+-----------
+
+The :ref:`bson_append_array_end()` function shall complete the appending of an array field
+started with :ref:`bson_append_array_begin()`. ``child`` is invalid after calling this function.
+
+Returns
+-------
+
+Returns ``true`` if successful.
+
+.. seealso::
+
+   | :ref:`bson_array_builder_t`

source/docs-libbson/bson_append_binary.txt

@@ -0,0 +1,43 @@
+.. _bson_append_binary:
+
+====================
+bson_append_binary()
+====================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   #define BSON_APPEND_BINARY(b, key, subtype, val, len) \
+      bson_append_binary (b, key, (int) strlen (key), subtype, val, len)
+
+   bool
+   bson_append_binary (bson_t *bson,
+                      const char *key,
+                      int key_length,
+                      bson_subtype_t subtype,
+                      const uint8_t *binary,
+                      uint32_t length);
+
+Parameters
+----------
+
+- ``bson``: A :ref:`bson_t`.
+- ``key``: The key name.
+- ``key_length``: The length of ``key`` in bytes or -1 to use strlen().
+- ``subtype``: A bson_subtype_t indicating the binary subtype.
+- ``binary``: A buffer to embed as binary data. May be ``NULL`` for an empty binary value.
+- ``length``: The length of ``buffer`` in bytes. Must be ``0`` if ``binary`` is NULL.
+
+Description
+-----------
+
+The :ref:`bson_append_binary()` function shall append a new element to ``bson`` containing
+the binary data provided.
+
+Returns
+-------
+
+Returns ``true`` if the operation was applied successfully. The function will fail if appending
+``binary`` grows ``bson`` larger than INT32_MAX.

source/docs-libbson/bson_append_bool.txt

@@ -0,0 +1,36 @@
+.. _bson_append_bool:
+
+==================
+bson_append_bool()
+==================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   #define BSON_APPEND_BOOL(b, key, val) \
+      bson_append_bool (b, key, (int) strlen (key), val)
+
+   bool
+   bson_append_bool (bson_t *bson, const char *key, int key_length, bool value);
+
+Parameters
+----------
+
+- ``bson``: A :ref:`bson_t`.
+- ``key``: The name of the field.
+- ``key_length``: The length of ``key`` or -1 to use strlen().
+- ``value``: true or false.
+
+Description
+-----------
+
+The :ref:`bson_append_bool` function shall append a new element to ``bson`` containing the
+boolean provided.
+
+Returns
+-------
+
+Returns ``true`` if the operation was applied successfully. The function will fail if appending
+the value grows ``bson`` larger than INT32_MAX.