Re: [boost] [review] Review of Outcome (starts Fri-19-May)

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:
> >> https://github.com/akrzemi1/__sandbox__/blob/master/outcome_intro.md
> >>
> > 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
Boost.Optional.

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

http://www.boost.org/doc/libs/1_64_0/libs/optional/doc/html/index.html

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

http://www.boost.org/doc/libs/1_64_0/libs/optional/doc/html/boost_optional/quick_start.html#boost_optional.quick_start.optional_return_values
http://www.boost.org/doc/libs/1_64_0/libs/optional/doc/html/boost_optional/quick_start/optional_automatic_variables.html
http://www.boost.org/doc/libs/1_64_0/libs/optional/doc/html/boost_optional/quick_start/optional_data_members.html
http://www.boost.org/doc/libs/1_64_0/libs/optional/doc/html/boost_optional/quick_start/bypassing_unnecessary_default_construction.html
http://www.boost.org/doc/libs/1_64_0/libs/optional/doc/html/boost_optional/quick_start/storage_in_containers.html

I would do the same for Outcome:

In the landing page just give this example:

https://github.com/akrzemi1/__sandbox__/blob/master/outcome_intro2.md

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.

Regards,
&rzej;