[boost] Re: Some remarks on PP docs

From: David B. Held (dheld_at_[hidden])
Date: 2004-06-10 12:04:04

"David Abrahams" <dave_at_[hidden]> wrote in message
news:uaczb9y4f.fsf_at_boost-consulting.com...
> [...]
>   It is usually okay to reuse a single generic macro name like
>   BOOST_PP_DEF throughout your code because the macro is
>   both defined and undefined very close to its point of use.

Yeah, this would make a lot more sense.  I was just looking over the
docs the other day too, and gave up because it was taking too long
to grok.

> [...]
> ?? Where is BOOST_PP_EMPTY used in this example?  I think I
> know what you mean, but really, you need to show it!

Yup.  You did better than me.  I didn't even see the
BOOST_PP_EMPTY.

> [...]
> The BOOST_PP_ENUM_PARAMS example could benefit greatly
> from a side-by-side format in a table showing the expansion on the
> right.  In fact, that would help all the examples,

YES!  I could not agree with this more!!!  It's hard enough getting one's
head around the PP lib without having to be an expert in it already.

> [...]
>   BOOST_PP_IF enables convenient generation of lists using
>   BOOST_PP_REPEAT.
>
> This statement, without an example, is too vague to be helpful.

Yes, many more examples, please.  Also, am I the only one who finds
the sparse frame-based layout to be a little counter-intuitive?  Would
it be possible to make the docs look a little more Boost-like?

> [...]
>   Example:  Use arithmetic, logical, and comparison operations
>   when necessary.
>
> With no commentary, and no generated code, this example is really
> useless.  I mean, of course you'd use arithmetic, logical, and
> comparison operations "when neccessary".

I didn't get that either.  It's a shame, because there's a lot of code that
would benefit from the PP lib that almost certainly isn't because of the
difficult learning curve.  Good documentation would go a long way
towards making it more usable.

Dave

---
Outgoing mail is certified Virus Free.
Checked by AVG anti-virus system (http://www.grisoft.com).
Version: 6.0.701 / Virus Database: 458 - Release Date: 6/7/2004