Boost logo

Boost :

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2002-03-08 07:40:17

----- Original Message -----
From: "vesa_karvonen" <vesa_karvonen_at_[hidden]>
To: <boost_at_[hidden]>
Sent: Friday, March 08, 2002 1:10 AM
Subject: [boost] Re: boost::bind and the preprocessor

> --- In boost_at_y..., "David Abrahams" <david.abrahams_at_r...> wrote:
> > The PP library documentation is still really hard to use. For
> > example, Just look at the docs for BOOST_PP_LIST_FOR_EACH_I.
> Just for the record, I'm not trying to be argumentative.
> Unfortunately a comment that says that something is "hard to use" or
> thay "[...] took me a very long time" doesn't really give any clue of
> how to make things better. Please be more specific. So,...


> Do you now know how to use BOOST_PP_LIST_FOR_EACH[_I]?

I figured it out eventually.

> If so, how
> would you document it? What was the source of difficulty? How would
> you eliminate the difficulty?

Answered all at once:

1. Make sure there's a prominent link which describes the purpose of the
R parameter. I ended up scouring through the other doc pages to figure
that one out

2. Add an example to the page. Every single macro should come with a
small example.

3. All examples should include not only the source text but the
resulting expansion

4. Provide more cross-references for definitions of terms. What's a
Tuple? What's a List? Each time you mention tuple or list in the
documentation, it would help to have a link to click.

> > Even getting started with elementary examples took me a very long
> > time.
> Was it difficult to find the examples?

It was difficult to translate the examples into something I could use.

> Was it difficult to
> compile/preprocess the examples? Was it difficult to understand the
> examples? What was the source of difficulty? How would you eliminate
> the difficulty?

Yes, the examples I could find were also difficult to understand because
they didn't show the intended results along with the source.

> > If you don't know anything about the library, how many other pages
> > do you have to look at in order to be able to understand how to use
> > it?
> Interesting, but under specified, question. The problem is that the
> ability to use any library (and I'm not talking about Boost.Any :)
> depends largely on the experience of the person attempting to use the
> library. A further problem with metaprogramming libraries is the
> motivation to use the library. Metaprogramming is still not a widely
> understood concept and people may have difficult time to understand
> the motivation.

Believe me, I'm plenty motivated, but if the barrier to entry is too
high I'll find other ways.


Boost list run by bdawes at, gregod at, cpdaniel at, john at