CDRIVER-3904 improve documentation regarding when to call mongoc_log_set_handler #739
Conversation
| @@ -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 logging document for details. | |||
There was a problem hiding this comment.
See logging document for details
I'm not sure how to link documents in .rst files. Could you provide an example, please?
There was a problem hiding this comment.
Sure. See the links in the webpage for aggregate opts here, specifically collation. The text file for it is in aggregate-opts.txt in this same directory.
Linking the logging header would be similar to the header link for Setting Collation Order. In other words,
- create an anchor to the header in src/libmongoc/doc/logging.rst (since one doesn't exist). For example,
.. _custom_log_handlers: // <- add anchor
Custom Log Handlers
-------------------
- Now you can link to that header from this text file. For example,
:ref:`Custom Log Handler<custom_log_handlers>`
If you'd like to test this locally you can follow the steps here for building the documentation. Afterwards, the HTML files will be in /build/src/libmongoc/doc/html.
| @@ -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 logging document for details. | |||
There was a problem hiding this comment.
Sure. See the links in the webpage for aggregate opts here, specifically collation. The text file for it is in aggregate-opts.txt in this same directory.
Linking the logging header would be similar to the header link for Setting Collation Order. In other words,
- create an anchor to the header in src/libmongoc/doc/logging.rst (since one doesn't exist). For example,
.. _custom_log_handlers: // <- add anchor
Custom Log Handlers
-------------------
- Now you can link to that header from this text file. For example,
:ref:`Custom Log Handler<custom_log_handlers>`
If you'd like to test this locally you can follow the steps here for building the documentation. Afterwards, the HTML files will be in /build/src/libmongoc/doc/html.
src/libmongoc/doc/logging.rst
Outdated
| @@ -100,6 +100,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()``. | |||
There was a problem hiding this comment.
Here mongoc_log_set_handler() needs two backquote keys around it for monospaced fonts to work.
Thank you very much for your feedback and detailed explanation. I have fixed the PR, hoping now could be merged. |
PR as discussed at #736 (comment)
Any feedback is welcome, including .rst syntax, documentation style in the Mongo C driver repository, or even text wording (English is not my native language ;)