Re: [Boost] [Describe] Review Reminder

From: Ruben Perez (rubenperez038_at_[hidden])
Date: 2021-03-09 21:46:47

Hi all,

This is my review for Boost.Describe. Thanks Peter for contributing the
library to the community.

My vote is to ACCEPT the library into Boost. See below for the full review.

On Fri, 5 Mar 2021 at 08:19, Richard Hodges via Boost <boost_at_[hidden]>
wrote:

> A friendly reminder that the review period for [Boost.Describe] is half way
> through.
> We've had some excellent feedback already, and would value more.
> If you can spare a few hours of your valuable time, please consider
> reviewing this neat little library and posing your results on this mailing
> list.
> The invitation is repeated below:
> The Boost formal review of the Describe starts Monday, taking place from
> March 1st, 2021 to March 10th, 2021 (inclusive).
>
> The library is authored by Peter Dimov.
>
> Documentation: https://pdimov.github.io/describe/doc/html/describe.html
> Source: https://github.com/pdimov/describe
>
> The library provides a simple means of providing reflection for structures
> and enums in C++.
>
> The documentation contains a number of common motivating examples,
> including:
>
> - A universal print function
>
> https://pdimov.github.io/describe/doc/html/describe.html#example_print_function
>
>
> - JSON serialisation
> https://pdimov.github.io/describe/doc/html/describe.html#example_to_json
>
> Please provide in your review information you think is valuable to
> understand your choice to ACCEPT or REJECT including Describe as a
> Boost library. Please be explicit about your decision (ACCEPT or REJECT).
>
> Some other questions you might want to consider answering:
>
>   - What is your evaluation of the design?

Good. It's a simple interface which covers many common use cases.
I'm especially interested in the POD (de)serialization use case, which is
covered nicely and simply.

Some extra features like describe_enumerators_as_array would be great, but
I understand those can be added later, and are not the main purpose of this
lib.

Supporting annotations when defining/describing structs would be a great
win, but the library is already useful without that.

>   - What is your evaluation of the implementation?
>

I haven't looked at the internals a lot. I value the fact that it has
minimal dependencies, as this makes adoption easier.
I've seen that BOOST_DESCRIBE_XXX introduce functions like
_base_descriptor_fn in user namespaces,
which could cause clashes - maybe prefixing those with _boost may be a good
option.

>   - What is your evaluation of the documentation?
>

Good. I would add in the main page a statement saying that this is a quite
low-level block, and that the intended use is for
- User code to use the BOOST_DESCRIBE_XXX macros to instrument the code and
- Generally other library code to use those definitions to do useful stuff
with that.
I think bringing the JSON example early (you as the user define
BOOST_DESCRIBE_XXX, JSON uses describe::describe_members
to implement serialization) may be beneficial por the public to understand
the scope of the library. Now it seems obvious to me, but it
may not be for the newcomer.

Usage examples are good. They might be a little bit frightening at first,
but they cover the main use cases.

>   - What is your evaluation of the potential usefulness of the library?
>

It's definitely very useful. If it gets into Boost, I will definitely use
it in Boost.Mysql (which I will be proposing shortly) to implement parsing
database rows into user-defined structs (hence my interest for describing
PODs). Again,  annotations would be beneficial but not mandatory for my use
case.

>   - Did you try to use the library? With which compiler(s)? Did you
>     have any problems?
>

I built a simple POD serialization/deserialization example, based on the
library's examples and my needs.
I used GCC9 on Linux, I had no problems.

>   - How much effort did you put into your evaluation? A glance? A quick
>     reading? In-depth study?
>

About 2 hours.

  - Are you knowledgeable about the problem domain?
>

I'm just a user in the field of reflection. It's a topic that interests me
as it has arisen many times in my career, but I am just a user.

>
> More information about the Boost Formal Review Process can be found
> at: http://www.boost.org/community/reviews.html
>
> The review is open to anyone who is prepared to put in the work of
> evaluating and reviewing the library. Prior experience in contributing to
> Boost reviews is not a requirement.
>
> Thank you for your efforts in the Boost community. They are very much
> appreciated.
>
> Richard Hodges
> - review manager of the proposed Boost.Describe library
>
> Peter is often available in the CppLang Slack #boost channel should you
> require any clarification not covered by the documentation, as am I.
>
> --
> Richard Hodges
> hodges.r_at_[hidden]
> office: [phone]
> home: [phone]
> mobile: [phone]
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
>