[boost.async] a note on documentation

From: Andrzej Krzemienski (akrzemi1_at_[hidden])
Date: 2023-09-22 14:34:17

Hi Everyone,
In the context of the Boost review of Boost.Async, I wanted to share a
thought on documentation.
I think the Reference section in the docs is insufficient. A lot of
libraries in Boost have this approach that the reference section of the
documentation is a specification exhaustive enough that it could be used to
provide a number of competing implementations. Each function has a very
detailed contract: what it returns and when, what are the preconditions,
what exceptions are thrown upon failure, what are the postconditions. I am
missing this from the reference of Boost.Async.

Also, it may be one of the first libraries (that meet a certain bar of
documentation) tied so much to coroutines, so I have no strict requirements
on how a coroutine library is documented, but I think things like promise
types should be explicitly referenced.

Let's consider `async::generator`. It is not only class template
`generator`, but also:

1. the specialization of type trait std::coroutine_traits
2. Class template `generator_promise`
3. generator_promise
4. generator_receiver
5. awaitable types

Even though some of them belong to namespace `detail`, they provide
guarantees relevant for the users. I do not think `generator_promise`is an
implementation detail. I think it needs to be documented. This seems
especially important when I start adding my awaitables to the mix.

I wonder what others think about it?

Regards,
&rzej;