Re: [boost] [outcome v2] Please comment on new result<T, EC> reference API docs

Subject: Re: [boost] [outcome v2] Please comment on new result<T, EC> reference API docs
From: Andrzej Krzemienski (akrzemi1_at_[hidden])
Date: 2017-06-22 07:43:11

2017-06-21 19:41 GMT+02:00 Niall Douglas via Boost <boost_at_[hidden]>:

> Dear Boost,
>
> I've been hard at work refactoring Outcome to match the peer review a
> few weeks ago. Much comment at the time mentioned the poor experience of
> the reference API docs, so can I get a community check of this:
>
> https://dedi4.nedprod.com/static/result-v2/doc_result.html
>
> This was generated by the new C++ reference docs generator
> https://github.com/foonathan/standardese. You'll no doubt spot quite a
> few formatting bugs, Jonathan says he's onto them. But the usage of
> libclang rather than doxygen's broken C++ parser clearly shows a lot of
> benefit, it's just standardese still remains quite a lot short in terms
> of necessary features to make output fully correct.
>
> I won't give the changelog for Outcome v2 result<T> over Outcome v1 yet.
> Let's see how you fare with the above reference API docs first. But as
> you'll note, there is considerable change over before as we now slot
> into a niche not occupied by Expected nor EitherMonad, indeed this now
> looks much more like Robert's or Lawrence Crowl's slimmed down object.
> This result<T> is approx 0.6 CPU cycles per stack frame unwound slower
> which I feel is acceptable in exchange for no more variant storage,
> which in turn released lots of SFINAE budget for me.
>
> (FYI v2 outcome<T> isn't done yet, but it will extend v2 result<T>)
>

Niall,
There is certainly more information now in the reference section than
before. This is clearly an improvement. You probably want to conceal some
of the types used for implementation from the docs, like those from
namespace `impl`, but I understand this is just a prototype.

One thing I want to suggest, is that the standardese used in the standard
Library has problems of its own, that you have a chance of avoiding. For
instance, as described here:
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0411r0.html

the "Requires" clause mixes two things: (1) requirements that can be (and
are) checked at compile-time (like DefaultConstructible), and (2)
requirements on values that if not met cause UB (like `i < this->size()`).
The linked paper proposes, and I encourage the same to use two different
clauses:

Precondition: i < this->size();
Requires: is DefaultConstructible

And as some have suggested, even a third one that describes all the
enable_if-s in the interface:

"Enabled_if: is_copyable_v<T>" instead of "Effects: this overload shall not
participate in overload resolution unless is_copyable_v<T> is true".

Regards,
&rzej;