The documentations never state what a false return value means. Does it mean a NULL was passed? Internal error, such as allocation errors? What sort of scenarios lead to a return value being false rather then true?
This needs to documented in one location and linked from functions with boolean return values

Following is the original report
—

The setters on mongoc_find_and_modify_opts_t like mongoc_find_and_modify_opts_set_sort and others generally return a bool and are documented as "Returns true if it successfully added the option to the builder."

There is no documentation of what "false" means. Looking at the code, some of them appear to have no way to return false. Others return false if their input is null. Without inspecting the code, we have no way of knowing if we should be checking the return value and without documentation, the behavior is unspecified and thus subject to change.

We are auditing all mongocxx calls to libmongoc to ensure mongocxx handles error conditions according to the libmongoc documentation. We can't do that if return value documentation isn't complete.

For all the setters, we would like the following changes to documentation:

• document what 'false' means OR document that the function only ever returns true