|
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:
> >> 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;
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk