Re: [boost] Re: boost::bind and the preprocessor

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,...

Sorry...

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

-Dave