Re: [boost] Yap's formal review is starting now!

Subject: Re: [boost] Yap's formal review is starting now!
From: Zach Laine (whatwasthataddress_at_[hidden])
Date: 2018-02-14 20:12:30

On Tue, Feb 13, 2018 at 10:54 PM, Barrett Adair via Boost <
boost_at_[hidden]> wrote:

> On Mon, Feb 5, 2018 at 9:53 AM, Louis Dionne via Boost <
> boost_at_[hidden]> wrote:
>

[snip]

Thanks for reviewing, Barrett!

> My only comment on the implementation is a minor usability note - a
> recurring point of frustration for me was that gcc 7.2 errors print
> expr_kind template value parameters as integer values instead using enum
> member names, e.g. `meow_expr<(boost::yap::expr_kind)18,
> boost::hana::tuple<meow>>`. This adds a layer of mental indirection when
> debugging an expression tree. A very small nice-to-have, if nothing else,
> would be to assign explicit enum values in boost/yap/algorithm_fwd.hpp for
> faster cross-referencing.
>

Simple enough.  Done.

> >   * Documentation
>
> ...can never be good enough, but I'm happy with this. It's pleasantly
> concise, and it seems complete. I'm confident that I could become
> proficient with Yap given what is available here.
>
> I do think the docs would benefit from the following:
> * less nesting of sections
> * a link to Zach's C++Now talk (if the talk still reflects the code, that
> is)
>

I fear this will be a lot less relevant in a week or so.

> * more examples, as always
>

Any suggestions?

> * Some sections could be merged, such as "operators" and "operator macros",
> also the transform sections
>

I have them separate only because I don't want to overload the reader with
too much detail (the macros part) too early.  Would it be sufficient to add
cross-links between the two sections?

For the same reason, I'm moving "Printing" to the very end.  Not sure why
it was in the middle there.

> * The "operator macros" section would benefit from having the expr_kind
> names listed nearby
>
> This documentation appears to cater to Proto alumni, which is fine, but an
> "Intro to Expression Templates" section would be nice for newcomers. A
> "Suggested reading" section would also be a cheap way to improve
> accessibility. Smoothing out the cliff-shaped learning curve of this
> library is a daunting task, but it might be worthwhile in the long run.
>

I'll add this.  I was a little surprised at the lack of familiarity with
expression templates, even at C++Now. *TODO*

Zach