Re: [boost] [outcome] Requesting pre-review of Boost.Outcome tutorial

Subject: Re: [boost] [outcome] Requesting pre-review of Boost.Outcome tutorial
From: Andrzej Krzemienski (akrzemi1_at_[hidden])
Date: 2016-11-21 19:33:54

2016-11-11 20:27 GMT+01:00 Niall Douglas <s_sourceforge_at_[hidden]>:

> Dear Boost,
>
> I am hoping to bring Boost.Outcome, a C++ 14 library providing a
> factory and family of policy driven lightweight monadic
> value-or-error transports, into the Boost peer review queue by March
> 2017 followed shortly thereafter by an ACCU talk in April if my talk
> proposal passes their programme committee. To that end, I've written
> an explanation and a sort of tutorial explaining the history and
> purpose of Outcome at https://ned14.github.io/boost.outcome/ and I'd
> greatly appreciate if people could tell me:
>
> 1. Does it make sense?
>
> 2. Do you think you could use Outcome in your own code after reading
> it?
>
> 3. Do you think you would want to use Outcome in your own code after
> reading it?
>
> 4. Are there any missing parts which are showstoppers?
>
>
> My thanks in advance. Be aware the install stuff described at the
> start doesn't work yet. The reference documentation is also quite
> patchy thanks to doxygen not understanding CRTP. All that stuff and a
> fair bit more remains to fix before it's ready to enter the Boost
> peer review queue.
>

Hi Niall,
I am very curious about your library, and about the subject. I would like
evaluate it. But I am having problems going through the documentation. I
was only able to figure out that it deals with returning either T or an
information about failure, and that you believe it is the fastest solution
you can get. But other than that, I am confused.

I am very found of Robert Ramey's advice given in this talk:
https://youtu.be/ACeNgqBKL7E?t=4m48s
And I would summarize it as follows, does the first page of the
documentation allow me to see and understand in 5 min what this library is
for and how I will be using it.

I admit that I am a bit impatient, but this also might be an important
feedback for you. I suppose, I am not the only impatient programmer that
would be a potential user of your library, but may be discouraged by the
documentation. It is clear that you have put a lot of effort into the
documentation, but I still cannot find my way around it.

It starts with installation guide, then design rationale, then the history
of error reporting in c++, then the long synopsis, and only at the end do
we find an example, but it is quite complicated, and not quite well
annotated, uses long names, and I am not even sure which names are part of
boost::outcome, and which names are only invented for the sake of the
example. I could only figure out that we have macro  BOOST_OUTCOME_TRY
<https://ned14.github.io/boost.outcome/monad_8hpp.html#aa977bf0b7aded30c781c35f956edc1d7>,
which is a sort of control flow.

Really, some simple, annotated examples should be the first thing we see in
the docs. In fact, there is a TODO at the top saying, "Add a vanilla use
case snippet here". I would really like to see such example. For an example
of what I mean, I recommend looking at the first pages of the documentation
for Boost.Optional:
http://www.boost.org/doc/libs/1_62_0/libs/optional/doc/html/index.html

Additionally, words "monad" and "monadic" appear quite often in the
documentation. I fail to see how this is supposed to help understand the
library. I am not familiar with FP, and this term distracts my efforts to
understand what this library is for.

I hope these remarks will help.
Regards,
&rzej;