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

From: Hans Dembinski (hans.dembinski_at_[hidden])
Date: 2019-05-27 08:31:26

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