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: Peter Dimov (lists_at_[hidden])
Date: 2017-06-21 21:49:46

Niall Douglas wrote:
> More importantly though, is that reference API documentation what people 
> were looking for? With clauses for effects, requires, throws etc?

Yes, this is the style the C++ standard uses.

> Do I need to write more detail for the APIs, or is what is there enough?

You could be more detailed in places. For example,

""
Function template outcome::policy::throw_directly::narrow_value_check

template <class Impl>
static constexpr void narrow_value_check(Impl* self) noexcept;

Performs a narrow check of state, used in the assume_value() functions
""

You have to say what happens, that is, you're missing the Effects clause 
here.

Another minor comment:

noexcept(noexcept(value_type(std::forward<T>(t)))&&noexcept(error_type(std::forward<U>(u))));

This is usually written as

noexcept(is_nothrow_constructible_v<value_type, T> && 
is_nothrow_constructible_v<error_type, U>);

If you haven't, you could look at the C++ standard to get an idea of how it 
specifies things, for example here: http://eel.is/c++draft/tuple.tuple

SmartPtr uses a similar style too, f.ex. here:

http://www.boost.org/doc/libs/develop/libs/smart_ptr/doc/html/smart_ptr.html#shared_ptr_members