Re: [boost] Preprocessor: documentation comment

From: Paul Mensonides (pmenso57_at_[hidden])
Date: 2002-06-13 19:47:43

> > The documentation would be clearer, if 'automatic recursion' was a link
> that
> > described what it is is.
>
> Is there any chance that you and Vesa will work together to clarify the
> docs, especially the tutorial section, while you are working on these cool
> functional improvements?
>
> -Dave

I have been corresponding with Vesa about some of this stuff already (not the
docs, but the implementation), and I think that it is hard to finalize at this
point.  For instance, Vesa's implementation of BOOST_PP_WHILE represents about
256 iterations.  If he was to apply automatic recursion to that entire list of
macros, then every one of those *_D macros (i.e. ADD_D, MUL_D, etc.) could be
gotten rid of entirely because they would be unnecessary.  The problem though is
that would be massively inefficient to perform that kind of check linearly on
256 macros.  There are several alternatives that I'm looking into (and Vesa is
also), such as only 'allocating' batches of iterations (i.e. only check every 5
or 10) or using a binary search (or a weighted binary search, or both) to
improve the efficiency of such a strategy.

As far as the documentation goes, it really needs a full-fledge introduction to
preprocessor meta-programming.  I.e. what kinds of idioms and techniques are
available, how to avoid certain traps, etc..  It also needs tutorials sections
about each separate subset of the library (i.e. working with tuples, working
with cons-lists, working with loops, working with arithmetic, etc.), and lastly
the documentation needs step-by-step examples (not just completed examples).

My main problem is that I don't thoroughly know the Boost.Preprocessor library.
I am getting to know it better as time goes by, but I have never actually *used*
it at all--just looked at, comprehended the implementation, and compared it to
my own implementation of the same type of thing.  Sometimes I like how it does
things better, sometimes not.  Also, I don't know if I have enough experience
with preprocessor meta-programming to make a relatively comprehensive
introduction to the techniques involved.  Though I may be more equipped for it
than many--and possibly more importantly, I have some interest in it.

Of course, this whole preprocessor thing was a huge side-trip from what I was
working on before (template meta-programming), which in turn was a huge
side-trip from what I was working on before that.

However, I have been talking with Vesa, and things are improving (at this point
the implementation).  Also, Vesa has told me that he plans to renovate the
documentation (except the reference part).  The hard part is coming up with
worthwhile examples that aren't really complicated--and that is why discourses
on feature sets are necessary.

I will talk to Vesa about it anyway though.

Paul Mensonides