CDRIVER-1909 improve init / cleanup docs

Author: ajdavis

doc/Makefile.am

@@ -8,7 +8,8 @@ EXTRA_DIST += \
   doc/mongoc-theme/static/mongoc.css_t \
   doc/mongoc-theme/static/pygments.css \
   doc/mongoc-theme/theme.conf \
-  doc/taglist.py
+  doc/taglist.py \
+  $(wildcard doc/includes/*.txt)
 
 dist-hook: man html
 

doc/includes/init_cleanup.txt

@@ -0,0 +1,3 @@
+Initialize the MongoDB C Driver by calling :symbol:`mongoc_init` exactly once at the beginning of your program. It is responsible for initializing global state such as process counters, SSL, and threading primitives.
+
+Call :symbol:`mongoc_cleanup` exactly once at the end of your program to release all memory and other resources allocated by the driver. You must not call any other MongoDB C Driver functions after :symbol:`mongoc_cleanup`. Note that :symbol:`mongoc_init` does **not** reinitialize the driver after :symbol:`mongoc_cleanup`.

doc/init-cleanup.rst

@@ -6,14 +6,30 @@ Initialization and cleanup
 Synopsis
 --------
 
-The MongoDB C driver must be initialized using :symbol:`mongoc_init <mongoc_init>` before use, and cleaned up with :symbol:`mongoc_cleanup <mongoc_cleanup>` before exiting. Failing to call these functions is a programming error.
+.. include:: includes/init_cleanup.txt
 
 .. only:: html
 
   .. toctree::
     :titlesonly:
     :maxdepth: 1
 
-    mongoc_cleanup
     mongoc_init
+    mongoc_cleanup
+
+Deprecated feature: automatic initialization and cleanup
+--------------------------------------------------------
+
+On some platforms the driver can automatically call :symbol:`mongoc_init` before ``main``, and call :symbol:`mongoc_cleanup` as the process exits. This is problematic in situations where related libraries also execute cleanup code on shutdown, and it creates inconsistent rules across platforms. Therefore the automatic initialization and cleanup feature is deprecated, and will be dropped in version 2.0. Meanwhile, for backward compatibility, the feature is *enabled* by default on platforms where it is available.
+
+For portable, future-proof code, always call :symbol:`mongoc_init` and :symbol:`mongoc_cleanup` yourself, and configure the driver like:
+
+.. code-block:: none
+
+  ./configure --disable-automatic-init-and-cleanup
+
+Or with CMake:
+
+.. code-block:: none
 
+  cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=NO

doc/installing.rst

@@ -83,7 +83,7 @@ The most recent release of libmongoc is |release| and can be `downloaded here <h
   $ cd mongo-c-driver-|release|
   $ ./configure --disable-automatic-init-and-cleanup
 
-For a list of all configure options, run ``./configure --help``.
+The ``--disable-automatic-init-and-cleanup`` option is recommended, see :doc:`init-cleanup`. For a list of all configure options, run ``./configure --help``.
 
 If ``configure`` completed successfully, you'll see something like the following describing your build configuration.
 

doc/mongoc_cleanup.rst

@@ -14,5 +14,4 @@ Synopsis
 Description
 -----------
 
-This function is responsible for cleaning up after use of the MongoDB C driver. It will release any lingering allocated memory which can be useful when running under valgrind.
-
+.. include:: includes/init_cleanup.txt

doc/mongoc_init.rst

@@ -14,7 +14,4 @@ Synopsis
 Description
 -----------
 
-This function should be called at the beginning of every program using the MongoDB C driver. It is responsible for initializing global state such as process counters, SSL, and threading primitives.
-
-When your process has completed, you should also call :symbol:`mongoc_cleanup <mongoc_cleanup>`.
-
+.. include:: includes/init_cleanup.txt