Re: The standard library is better documented

From: Andrzej Krzemienski (akrzemi1_at_[hidden])
Date: 2023-12-02 16:53:25

sob., 2 gru 2023 o 16:58 René Ferdinand Rivera Morell via Boost <
boost_at_[hidden]> napisał(a):

> On Sat, Dec 2, 2023 at 2:08 AM Niilo Huovila via Boost
> <boost_at_[hidden]> wrote:
> >
> > By better I mean cppreference.com. There's a page for pretty much
> > everything in the standard library. Related pages are linked. The
> > preconditions and behavior of functions are specified. Consequentially I
> > come to Boost only when the standard library doesn't do enough. If you
> > are going to compete with the standard library instead of just
> > supplementing it, you need outstanding documentation.
>
> It would be useful if you could point to instances of Boost libraries
> that could use better documentation.
>

The one that I have in mind is Boost.Cobalt. I am picking on it only
because we recently reviewed it, so it is fresh.
Consider the documentation for cobalt::left_race:
https://www.boost.org/doc/libs/1_84_0_beta1/libs/cobalt/doc/html/index.html#left_race

Documenting it is challenging as we do not have much experience with
documenting awaitables. We probably need to introduce another category
apart from "Expects", "Ensures", "Returns", "Effects": something like
"Await result" that describes what happens when you co_await on the
returned awaitable. More on this in
https://github.com/boostorg/cobalt/issues/138

Regards,
&rzej;

>
>
> --
> -- René Ferdinand Rivera Morell
> -- Don't Assume Anything  -- No Supone Nada
> -- Robot Dreams - http://robot-dreams.net
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
>