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-21 22:25:07

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

Great point.

> 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>);

I was trying to work around an ICE on MSVC :(

But it's not working, so I'm putting it back to how you describe.

> 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

I find writing this overspecification highly unnatural to me. It's not
how I think about APIs at all.

Thanks for your feedback Peter. Good to know this sort of documentation
is what people want. I'll keep pressing onwards.

Niall

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