[boost] [proto] comments on documentation #2

From: Markus Werle (numerical.simulation_at_[hidden])
Date: 2008-03-15 09:27:22

Hi!

<anecdote>
This morning (6:45 CET) I was sitting at the breakfast table and 
was reading the printed PDF of proto docs. 
My little son (6 years old) entered the scene and the first question 
he asked was: "What kind of puzzle are you trying to solve?".
Kids always have a keen sense of what's really going on ...
</anecdote>

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. 

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.

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.

Nothing of this part of the docs reached my heart and mind.
Without tiny little examples I am totally lost here.
This serves well as reference documentation, but not as
main entry point to a feature of a library.

I will try to work through the examples now, but any
introductory material appreciated here.
Keep me informed about updates in that section, please.

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.

extends<> is useful even without transforms and so why not
give it a chance before readers are drawn away by the
more advanced, but horrible-to-catch features.

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.

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.

-------------------------------------

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++. How about 

typedef ...implementation defined ... result_type;

Then move the decltype stuff to the comment paragraph below the code
as extra information.

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

-----------

Could you provide a full (compilable) example for increment_ints?
That would help education (though I feel like I got that one)
Maybe even extend the example to an initialization action based 
on operator new ...

-----------

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!
-----------------------------------------------------------

Now it is time to share some time with the kids.
Read you later in this group ...

Markus