Re: [ boost.out_ptr ] [ Review Endorsement ] New Library targeting C++11

From: JeanHeyd Meneide (phdofthehouse_at_[hidden])
Date: 2019-05-27 09:43:57

Dear Hans,

     Thank you for your feedback. I updated the documentation, top-level
landing page, rationale and overview accordingly.

Sincerely,
JeanHeyd

On Mon, May 27, 2019 at 4:28 AM Hans Dembinski <hans.dembinski_at_[hidden]>
wrote:

> Hi,
>
> > On 27. May 2019, at 08:00, JeanHeyd Meneide via Boost <
> boost_at_[hidden]> wrote:
> >
> >     After a lot of work and discussion in-person, via e-mail, and on the
> > Slack, I would like to ask for the library boost.out_ptr
> > <https://github.com/ThePhD/out_ptr/blob/master/docs/out_ptr.adoc> --
> > targeting C++11 -- to be endorsed for review.
> >
> >     Documentation: ascii doc-ready and readable on GitHub
> > <https://github.com/ThePhD/out_ptr/blob/master/docs/out_ptr.adoc>
> >     Repository: GitHub <https://github.com/ThePhD/out_ptr>
> >     Standards Proposal: p1132
> > <https://thephd.github.io/vendor/future_cxx/papers/d1132.html> (accepted
> > for and targeting C++20)
>
> this seems like a useful project, but reading the docs is frustrating. I
> find them less approachable than they should be. Here is some feedback:
>
> https://github.com/ThePhD/out_ptr/blob/master/docs/out_ptr/rationale.adoc
>
> It should be explained what CTAD is and/or a link to its definition should
> be provided. Just dropping acronyms is bad. If the authors expect the user
> to read p1132, before reading this page, that should be stated here.
>
> I am also missing a simple and concise explanation what kind of behavior
> outptr implements. In p1132, it says in the abstract:
>
> "out_ptr is an abstraction to bring both C APIs and smart pointers back
> into the promised land by creating a temporary pointer-to-pointer that
> updates the smart pointer when it destructs."
>
> This abstract is not telling me what exactly outptr is doing. It "updates"
> the smart pointer, that's very vague, you can be specific. outptr is very
> simple, so it should be possible to explain its behaviour in one or two
> sentences.
>
> From looking at the examples, I deduce that it converts any smart pointer
> to the corresponding raw pointer that can be passed to the C API and calls
> "release()" on the resource on destruction. I can't find this simple
> statement neither in the rationale nor in the abstract of n1132.
>
> The section "Motivation" starts with an example, that's bad style. first
> give a bit of intro and then show the example.
>
>
>
>
> https://github.com/ThePhD/out_ptr/blob/master/docs/out_ptr/overview.adoc
>
> This page is helpful, but the example should be cleaned of distracting
> stuff like
>
> ```
> PWM_AXIS_ZERO,
>         VLT_LOW_POW | VLT_POW_SAVE,
>         0x001B
> ```
>
> A minimal example is:
>
> ```
> boost::shared_ptr<shared_resource> shared_resource_ptr;
> errno err = some_c_api(&shared_resource_ptr);
> if (err != SUCCESS) {
>         // error handling code
> }
> ```
>
> Best regards,
> Hans