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 21:00:45

On Tue, Feb 13, 2018 at 7:07 PM, a.hagen-zanker--- via Boost <
boost_at_[hidden]> wrote:

> > We encourage your participation in this review. At a minimum, please
> state:

Thanks for reviewing, Alex.

> * Boost YAP review notes
>
> The documentation could be a lot more accessible. First of all it would be
> good if you could limit the references to Proto, this is not helpful for
> users who don't know Proto. Perhaps one separate page where you list the
> difference between Proto and Yap would be useful.

Yeah, I'm getting the impression you're not alone in not having used
Proto.  I'll do exactly as you suggest here.  *TODO*

> Next, remove all the jokes. Some are funny and others not, but none are
> helpful. And when trying to get my head around how to use the library, it
> is annoying to read the same joke again-and-again. (Yes, it took me many
> reads to understand what the library is offering exactly). The bloggy
> casual style is annoying me, when I am trying hard to make sense of the
> library.
>

Well, I'm a pretty casual person.

> Don't use examples without explaining what they are an example of.
>

Could you give an example?  No snark, I just don't know exactly what you're
referring to here.

> It would be good if the documentation page could include a definition /
> explanation of what an expression template is.

Agreed.

> Actually, I think you need to define what an expression is in this
> context. In my book, expressions are not just made of operators, but can
> also include function calls. However, the implicit impression I get from
> the YAP documentation is that you only consider expressions based on
> operators, and not functions. For instance, I consider std::sqrt(x) an
> expression. However, looking at expr_kind (https://tzlaine.github.io/
> yap/doc/html/boost/yap/expr_kind.html) it seems that this kind expression
> is not supported, (but it could be as a Transform).
>

That's supported.  std::sqrt(x) would need to be Yap-ified if x is not
already Yap expression, perhaps by making a sqrt Yap terminal, or by
calling std::sqrt on a Yap expression.  Assuming x is a Yap expression, the
entire expression "std::sqrt(x)" is a Yap expression whose kind is
expr_kind::call.  This underscores the need to make this more explicit in
the docs, though. *TODO*

> *Section Compiler Support
> I don't think it is acceptable to produce a library that cannot be
> compiled in MSVC own front-end.I can see that Hana got away with it on the
> premise of being ground-breaking and pushing the boundaries. However, YAP
> is not trying to be groundbreaking, it is offering stuff that Proto already
> offered and generalizing functionality of Eigen, UBLAS and others.

Yap's feature set is essentially a superset of Proto's, but with reasonable
compile times. That is something that no library has done before.  This is
literally the definition of groundbreaking.  But I take your point.  You
want MSVC support.

> Can you really not support MSVC? What is the bottleneck, and did you try
> to work around it?
>

MSVC does not have a conforming C++14 compiler.  Its constexpr support is
quite bad.  Louis Dionne has mentioned that the MSVC team is explicitly
trying to get Hana working as part of its recent development efforts.
Hopefully such changes land soon.  I'm not terribly interested in
undertaking herculean efforts to make a constexpr-friendly and
metaprogramming-heavy library work on a constexpr- and
metaporgramming-unfriendly compiler.  Some Boost libraries do that and some
do not, and this has been the case for years.

> *Section Dependencies
> Why depend on Hana, my impression of Hana and the associated review /
> discussion is that this library is made for demonstration of next
> generation C++ rather than actual use.
>

Because it makes everything having to do with tuple use and manipulation
easy.  This is why we make and use libraries, right?  So we don't each have
to reinvent the wheel?

Also, a 4-year-old standard is no longer appropriately called "next
generation C++," especially when it's not even the most recent one.

> *Section Header Organisation
> "If you want to ensure that you don't accidentally use expression<> (which
> I recommend),"
>
> I suppose you mean to recommend not using expression<>, WHY do you offer
> it? At this stage it does not make sense to talk about a thing I could do,
> but rather shouldn't. You haven't told me anything yet and are confusing me
> with expression<>: it is there but don't use it... How would I
> 'accidentally ' use it.
>

I'll make this clearer in the docs.  The idea here is that expression<>
exists for limited uses of Yap where no code is required for your
expression template itself -- you just use expression<>.  Such cases are
small ET systems local to a TU, which are essentially an implementation
detail; quick sketches or prototypes to get the broad strokes of an ET
solution before actually implementing your own template(s); and sloppy
individuals who don't really care about type safety. *TODO*

> *Section Expressions
> https://tzlaine.github.io/yap/doc/html/boost_yap__proposed_/
> manual/tutorial/expressions.html
>
> The language used in the documentation could be much more precise.
> Superfluous qualifications can be removed and at times detail can be added.

[snip]

 All the remaining comments are an indication to me that the introduction
of new ideas in the docs needs to be more slower-paced and explicit.  And
that bost:: is not a thing.  I'll make those changes.  *TODO*.

Zach