On Sat, May 28, 2022 at 3:39 PM Andrzej Krzemienski via Boost < boost@lists.boost.org> wrote:
Hi Everyone, I wanted to share an observation. A number of Boost libraries, in documentation, when it comes to demonstrating that a given function throws an exception, has a code sample like the following:
try {
lib::function(); } catch(lib::exception const&) { // handle failure }
This applies for instance to: * Boost.Lexical_cast:
https://www.boost.org/doc/libs/1_79_0/doc/html/boost_lexical_cast/examples.h...
* Boost.Optional:
https://www.boost.org/doc/libs/1_79_0/libs/optional/doc/html/boost_optional/...
* Boost.URL, waiting in the review queue: https://master.url.cpp.al/url/parsing/url.html
What bothers me is that this is a very dangerous antipattern related to handling exceptions.
I agree, it is not the job of the documentation of a function to show how to handle errors, only to specify the behavior of the function. Ideally this should be done formally, using this pattern: 1) Requires: lists the requirements that must be met in order for the function call to be valid. The user is not allowed to call the function otherwise. 2) Effects: specifies how the state of the program is altered by the function call. 3) Postconditions: the conditions that are guaranteed to be in place upon return from the function (if it doesn't throw). 4) Throws: lists exceptions that may be thrown if the postconditions could not be established. 5) Exception safety: specifies the state if an exception was thrown. For an example, see the documentation of the pointer constructor of shared_ptr: https://www.boost.org/doc/libs/1_79_0/libs/smart_ptr/doc/html/smart_ptr.html... . That said, it can be useful to demonstrate how to handle errors, but this wouldn't be attached to a particular function -- rather, it would show a pattern of correct error handling using the library.