Re: [boost] [Boost-users] [afio] Formal review of Boost.AFIO

Subject: Re: [boost] [Boost-users] [afio] Formal review of Boost.AFIO
From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2015-08-24 05:27:02

On 24.08.2015 04:29, Niall Douglas wrote:
> On 24 Aug 2015 at 0:46, Vicente J. Botet Escriba wrote:
>
>>>> I believe that I need something more about monad<T> than what I have
>>>> found in the documentation.
>>> If there is anything missing, please do say in detail.
>>>
>> Is this link part of the review? I don't believe, so could you point me
>> where the monad class is documented in AFIO? If it is not documented,
>> why it is used so broadly.
>
> It is used in the tutorial because as we progress through each stage
> of increasing complexity, you can see that the data_store class
> member functions lookup() and write() have either a monad<T> or a
> shared_future<T> return type depending on whether the API is
> synchronous (monad<T>) or asynchronous (shared_future<T>).
>
> I was trying to keep the interface class for each stage as identical
> as possible, so monad<T> was a natural fit to make the STL iostreams
> example look exactly like the AFIO asynchronous example. I suppose
> what you're saying here is that the tutorial should not be using
> monad<T> because monad<T> is not documented in AFIO.
>
> I can easily rewrite the tutorial code to not use monad<T>, it's no
> problem.
>
>>> If you want to pin a specific ABI which won't break in the future,
>>> you bind afio like this:
>>>
>>> namespace afio = BOOST_AFIO_V2_NAMESPACE;
>>
>> Where can I find the description of this macro on the reference
>> documentation?
>
> https://boostgsoc13.github.io/boost.afio/doc/html/afio/quickstart/workshop/naive.html
>
>> We have two options:
>> * we wait to review AFIO once Monad is reviewed in Boost
>> * You include in AFIO, whatever you consider is need from Monad and only
>> then we review AFIO.
>
> I can remove monad<T> from all the tutorial code. Or I can include
> documentation of monad<T> in AFIO. Which would you prefer?

Niall, I think you're missing the point. Is monad<T> part of the library 
interface? I.e. is the user allowed to use it to work with the library? 
If the answer is yes then it's a public part of the library and should 
be documented and reviewed. It doesn't matter if it is possible to code 
around it. If the answer is no then why is it there in the first place?