Skip to content

CDRIVER-3904 improve documentation regarding when to call mongoc_log_set_handler #739

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Feb 22, 2021
Merged

CDRIVER-3904 improve documentation regarding when to call mongoc_log_set_handler #739

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fa3b797
CDRIVER-3904 improve documentation regarding when to call mongoc_log_…
fgalan Feb 16, 2021
0958d89
CDRIVER-3904 fix issues in documentation raised during pull request r…
fgalan Feb 22, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions src/libmongoc/doc/includes/init_cleanup.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See logging document for details

I'm not sure how to link documents in .rst files. Could you provide an example, please?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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,

  1. 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
 -------------------
  1. 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.


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`.
3 changes: 3 additions & 0 deletions src/libmongoc/doc/logging.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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()``.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here mongoc_log_set_handler() needs two backquote keys around it for monospaced fonts to work.

Otherwise, some log traces could not be processed by the log handler.

To restore the default handler:

.. code-block:: c
Expand Down