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

Subject: Re: [boost] [outcome] Requesting second pre-review of Boost.Outcome tutorial
From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2017-01-26 05:05:27

>> This is a nice description. Thank you. But as you'll see in v3 of the
>> docs, I've completely rearchitected the message. Now Outcome looks like
>> it's primarily an implementation of LEWG Expected, and it provides a few
>> refinements of Expected which most users won't care about
>> or will refuse to use.
> 
> Well, how about just calling it "expected" and "selling" it as an
> alternative to std::expected?  There's lot's of precedent for this.  We
> have boost::shared_ptr, boost::enable_if, etc.  These have features that
> the std versions don't have and sometimes are indispensable for this
> reason.

I would think doing that unwise:

i) I'm not on the LEWG (can't justify the expense).

ii) Mine is not the reference implementation of Expected which ought to
take primacy.

iii) I am going to explicitly promise that my Expected WILL change to
match the LEWG propsal as it evolves, breaking the code of anyone who
uses it. If people don't like that, use outcome<T> or result<T>, those
won't change.

iv) I believe Vicente still intends to bring the reference Expected to
Boost at a later date. All his efforts are currently being expended on
WG21 work. But I could see a Google Summer of Code this summer being
just that for example.

I personally speaking believe anyone using unrestricted Expected
directly needs their head examined, but there are an awful lot of people
who think unrestricted Expected usage is an amazing thing. They need to
be convinced they are wrong. Hence Outcome is really a "please don't use
Expected directly, use these instead" library but also one handing them
the noose of unrestricted Expected usage if they really, really want it.

>> Not only has your feedback and discussion been very valuable, I don't
>> think the v3 tutorial would look like it does now without you.
> 
> make sure that your documentation has an acknowledgements section so you
> can mention this.

Good point.

>> Do let me know if the v3 tutorial now makes sense to you. I even dove
>> into "noexcept as can't fail" vs "noexcept can fail" as a nod to you :)
> 
> I'm gratified that you've taken the task of documentation as an integral
> part of developing the library.  I've been flogging this idea in the
> boost incubator.  I've got a lot to say about this there.

I would more describe it as a cross to carry whilst being whipped on the
road to Golgotha. Lucky I'm Catholic. I'm reaching the point where I'd
prefer a broken arm to rewriting the damn tutorial yet again, the fact
people need stuff spelled out to them in such incremental and precise
detail and can't just mentally fill in the very obvious small gaps I
find extremely frustrating.

Still, as you would say Robert, that's the price of good documentation.

Niall

-- 
ned Productions Limited Consulting
http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/