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: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2017-06-22 17:46:29

> 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.

Namespace impl is purely due to current limitations in the standardese
tool. It's supposed to be namespace detail.

> 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".

Enhancement submitted to https://github.com/foonathan/standardese/issues/62

Niall

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