On Sat, May 28, 2022 at 3:39 PM Andrzej Krzemienski via Boost
* Boost.URL, waiting in the review queue: https://master.url.cpp.al/url/parsing/url.html
Boost.URL is designed for the model where a thrown exception terminates the program. Such as when the author knows that the inputs are valid. People writing Real World Applications (TM) are not going to be throwing on untrusted inputs, they are going to be using the APIs which use error codes.
What bothers me is that ...Such examples...lead...young programmers into thinking that exceptions are difficult or illogical.
The goal of the examples that show exceptions in the documentation is merely to demonstrate that the exception is thrown. It is expected that the reader is in possession of sufficient ability so as to be able to make a leap of induction and apply this knowledge to their particular use case (where the exception handler may be in another function).
One could say that the goal of the documentation is to demonstrate, in an efficient way, the interface of the library: not to teach how to program.
Yes that is precisely the mindset when I write documentation. I assume that the user of the library already understands everything in the C++ language, everything in the standard library, and a reasonably average grasp of algorithms and general terminology. And I have a very good reason for doing so. It is because the user who lacks these things can always go someplace else to learn it (or teach themselves). External resources which specialize in teaching C++ are going to do a better job than I could. It is already hard enough to develop a Boost-quality library with Boost-quality documentation. Trying to also teach novices the techniques that are applicable to any code in general only creates additional work. Or to put it another way, having N authors of N libraries all trying to solve the same problem is not efficient.
I would like to know if there are more people in this list that feel the same way. Maybe we could come up with a systematic way of demonstrating a throwing library interface, or guidelines for documentation authors.
I think there is room for a project (or projects) aimed towards providing code and exposition for the purpose of learning C++, aimed towards individuals who do not "know Asio, know HTTP, know concurrent programming, and know error handling" (these the requirements for using Beast). This could be a Boost-branded offering available on its own from our the new website, with its own pages and discussion area. The C++ Alliance is open to explore implementing such a project if there are volunteers. I imagine that if started, such a resource would only continue to grow in size, utility, and participation over time (as it likely could never be correctly described as "done"). Thanks