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

Subject: Re: [boost] [outcome] Requesting pre-review of Boost.Outcome tutorial
From: Oswin Krause (Oswin.Krause_at_[hidden])
Date: 2016-11-11 16:57:01

Hi,
On 2016-11-11 20:27, Niall Douglas wrote:
> 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?
No, I think not that the documentation makes sense in the current form.

It implicitely assumes that the reader is familiar with a) c++ commitee 
speech (LEWG) and b) with future standard classes, e.g. expected. While 
some of those things are explained later on, up to the point where they 
are, their usage and discussion is confusing and distracting. Currently 
i have to scroll over several pages of text before I see what your 
library is about.

Even when jumping directly to "Introducing outcome", I have still to 
scroll over a wall of text and a quite long synopsis before seeing the 
first example - which again is not as vanilla as it should be.

> 
> 2. Do you think you could use Outcome in your own code after reading
> it?
probably not. It misses any simple vanilla example to just play around 
with. The only example given has so much clutter, that it makes it hard 
to even find the parts relevant to outcome (it took me roughly 30 
seconds to parse the function signature of file_create. I first could 
not even find result<file_handle>, which is somewhere in the middle of 
line 3, further to the right than all other function argument types.)

> 3. Do you think you would want to use Outcome in your own code after
> reading it?
probably not. The whole documentation seems to be designed to make your 
library look extremely complicated. So, unless forced to use it, I would 
try to avoid it.

> 4. Are there any missing parts which are showstoppers?
Unable to rate this. The above are show stoppers.

Best,
Oswin