Re: [boost.async] a note on documentation

From: Klemens Morgenstern (klemensdavidmorgenstern_at_[hidden])
Date: 2023-09-22 15:01:08

On Fri, Sep 22, 2023 at 10:34 PM Andrzej Krzemienski via Boost
<boost_at_[hidden]> wrote:
>
> 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