CDRIVER-3904 improve documentation regarding when to call mongoc_log_…

…set_handler (#739)

src/libmongoc/doc/includes/init_cleanup.txt

@@ -1,3 +1,5 @@
 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.
 
+Exception to this is ``mongoc_log_set_handler()``, which should be called before ``mongoc_init()`` or some log traces would not use your log handling function. See :ref:`Custom Log Handlers <custom_log_handlers>` for a detailed example.
+
 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`.

src/libmongoc/doc/logging.rst

@@ -65,6 +65,8 @@ To make logging a little less painful, various helper macros are provided. See t
 
   MONGOC_WARNING ("An error occurred: %s", strerror (errno));
 
+.. _custom_log_handlers:
+
 Custom Log Handlers
 -------------------
 
@@ -100,6 +102,9 @@ For example, you could register a custom handler to suppress messages at INFO le
      return 0;
   }
 
+Note that in the example above ``mongoc_log_set_handler()`` is called before ``mongoc_init()``.
+Otherwise, some log traces could not be processed by the log handler.
+
 To restore the default handler:
 
 .. code-block:: c