Re: [boost] [proto] comments on documentation #2

From: Eric Niebler (eric_at_[hidden])
Date: 2008-03-15 16:47:48

Markus Werle wrote:
> Before I start nagging, I should say that a large subset of the
> docs are well-done, near perfect. The setup of the first chapters
> makes it easy to approach proto. 

Thanks.

> But I got lost in the middle with transforms and that is a
> BadThing (TM), because those are the beasts everybody needs 
> in order to get the maximum out of proto.

Transforms are certainly the hardest-to-grok part of Proto. They're also 
the newest part of Proto. The docs here could certainly be better.

> The transform chapter leaves me with the same feeling I had 
> 1998, 2 weeks after my decision to learn C++, when I was
> reading Stroustrup's TCPPL chapter about templates. 
> I wish Vandevoorde/Josuttis would have written their book
> _before_ I had to use templates (and gcc).
> Same here: I beg for some step-by-step-by-example 
> introduction right now.

This section needs some motivating examples.

<snip>

> Minor issues:
> 
> First of all: Expression Extensions can go a long way without 
> transforms. So I would recommend to put this chapter in front of 
> the one about transforms. Then introduce transforms later for 
> those with the sword of metaprogramming knowledge and the will
> to survive.

A good suggestion.

> Also it might make sense to show an example which uses std::algorithms
> like the original std::transform example in order to show the power 
> of proto here.

Now that I have a Lambda example, I should reference it from the 
Expression Extension section.

> AFAICS _make_terminal drops in from heaven without introduction - right?
> Do we need that one? is terminal<>::type not equivalent? if yes, remove
> _make_terminal.

We need std::make_pair(), strictly speaking, but it's convenient. Same 
for _make_terminal. It's a typedef for 
functional::make_expr<tag::terminal> -- handy when writing transforms. 
If you object to my dropping it in here without describing it anywhere, 
that's a fair objection.

> The decltype stuff distracts from the key points.
> Unaware readers get into panik when seeing static references to types
> and a keyword yet not in C++.

<snip>
Agreed.

> Also: why ::result_type and not ::type? Is this consistent with mpl?

It's a TR1 function object, not an MPL metafunction.

> Could you provide a full (compilable) example for increment_ints?
> That would help education (though I feel like I got that one)

Sure.

> Maybe even extend the example to an initialization action based 
> on operator new ...

I don't follow.

> sed -es,no temporaries!,no temporary vectors!,g
> 
> Maybe state that there are no temporary vectors, but of course the integer 2
> in stored as temporary in [2]. Also state that every modern compiler
> since intel's 8.1 is capable of optimizing that one away, so nobody should
> care, and then: Look ma! no template code on-board after optimization ->
> the abstraction penalty is zero!

Right!

-- 
Eric Niebler
Boost Consulting
www.boost-consulting.com