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
Hi,
On 27. May 2019, at 08:00, JeanHeyd Meneide via Boost < boost@lists.boost.org> 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_ptr; errno err = some_c_api(&shared_resource_ptr); if (err != SUCCESS) { // error handling code } ``` Best regards, Hans