2017-06-21 19:41 GMT+02:00 Niall Douglas via Boost
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;