Boost logo

Boost :

Subject: Re: [boost] [review] Review of Outcome (starts Fri-19-May)
From: Andrzej Krzemienski (akrzemi1_at_[hidden])
Date: 2017-05-24 15:24:08

2017-05-24 17:00 GMT+02:00 Niall Douglas via Boost <boost_at_[hidden]>:

> >>> This means, the initial example should use `boost::outcome::result`
> >>> (instead of `boost::outcome::outcome`). And then function that
> >>> inspects the
> >>> result could read:
> >>>
> >>> ```
> >>> void test()
> >>> {
> >>> if (auto r = fun)
> >>> use_int_value(r.value());
> >>> else
> >>> inspect_error_code(r.error());
> >>> }
> >>> ```
> >>>
> >> The initial example could look like this:
> >>
> >>
> > THis is a better example of what Outcome can do, yes.
> You both would prefer that the landing page motivating example not show
> how outcomes can also transport caught C++ exceptions through non-C++
> exception code?

Actually, what I am suggesting goes beyond the initial example. My
suggestion is driven by the advice form Robert Ramey: that the potential
users are impatient: you have like 1 minute to attract their attention, and
like 5-10 minutes to go through the features without loosing their interest.

So, I would do something like we have in the documentation for

The initial page is very short. Short description and a really small
example. In fact too small to sell the power of this library:

And then in a number of subsequent pages, we describe feature by feature
with short examples:

I would do the same for Outcome:

In the landing page just give this example:

It only introduces `outcome::expected` (lot of users will not have heard of
`std::expected`) and the TRY operation to attract attention of more
informed users.

Then in the second page I would provide a number of short capters each with
one annotated example, each introducing one feature:

   - one for using payload wit error_code
   - one for all TRY operations
   - one for interaction with exception_ptr
   - one for catching exceptions into `outcome`
   - one for different ways of accessing the state of `outcome`

If you like this idea, I would volunteer to write up the initial pages.


Boost list run by bdawes at, gregod at, cpdaniel at, john at