On Fri, Sep 22, 2023 at 10:34 PM Andrzej Krzemienski via Boost
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.
Post-conditions are not really a good fit for asynchronous code I fear, especially since a user can omit a co_await. You'd end up with a confusing mess IMO. But I might add, that I don't like to read this kind of documentation either.
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.
I did this by having base types for each promise which are indeed documented https://klemens.dev/async/reference.html#generator-promise
Let's consider `async::generator`. It is not only class template `generator`, but also:
1. the specialization of type trait std::coroutine_traits
It doesn't have that specialization.
2. Class template `generator_promise`
3. generator_promise
Not directly documented, but it's properties are listed See here https://klemens.dev/async/reference.html#generator-promise
4. generator_receiver
Why would this need to be documented? That's clearly an implementation detail.
5. awaitable types
Documented as a concept here: https://klemens.dev/async/reference.html#awaitable
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.
It shouldn't be. The recommended way is to check for associators through concepts, as describe here: https://klemens.dev/async/design.html#associators
I wonder what others think about it?
Regards, &rzej;
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost