Re: [boost] Re: Re: Boost preprocessor library

From: David Abrahams (dave_at_[hidden])
Date: 2003-01-14 11:15:51

"Edward Diener" <eddielee_at_[hidden]> writes:

>
> My suggestion is not a programming primer on advanced techniques of using
> the preprocessor. It is rather an overview of the functionality in the
> preprocessor library broken down into categories of usage so that someone
> first trying to understand the facilities of the library can absorb what
> areas of functionality are there, and which groups of macros pertain to each
> area of functionality. That would make it easier looking at the reference
> section and understanding how any given macro relates to the library
> functionality as a whole. I realize that many of the macros are general
> purpose utility macros, but without a decent overview of functionality and
> organization it is really hard to understand why one should use areas of the
> preprocessor library in own's own code, whether one is a library implementor
> oneself or just a programmer writing modules and looking to use Boost.
>
> This is just a suggestion. I have had the same feelings regarding the
> documentation of a few of the other Boost libraries in that a general
> overview and categorization of functionality is lacking before the
> documenter explains details. As someone who has worked on 3rd party
> libraries myself, although not within the Boost framework, I know how easy
> it is not to realize that the functionality which the implementor implicitly
> understands is difficult for others to equally understand and use without a
> good preliminary explanation and breakdown of areas of usage.

I agree that this would be very helpful. Something along the lines of:

  "The Boost PP lib is a (mostly) functional programming system built
  around the C/C++ preprocessor.  The result of evaluating a Boost PP
  program is some new sequence of tokens, i.e. source code.
  
  You can do simple integer arithmetic which generates new computed
  preprocessor tokens. In other words, BOOST_PP_ADD(1,2) produces the
  token "3" instead of "1+2"

  You can do other computed generation of source code.

  You can smooth over implementation errors in common preprocessors by
  using macros such as BOOST_PP_CAT(a,b) instead of primitives such as
  ##.

  You can generate boilerplate source code repetition with computed
  variations in each repeat.  There are two main category of
  repetition, horizontal and vertical. The difference is blah, blah,
  blah.  Many repetition primitives accept an argument which is the
  name of a user-defined macro which is invoked with sequential
  numbers as one of the arguments, so that you can change the code
  generated for each repeat. You can read about horizontal repetition
  primitives here: ..., and vertical repetition primitives here:
  ... . A guide to choosing between the two idioms is here: ...
  "

This is very coarse, and also very short.  However, even something
like that on the front page of the documentation would be a big help.
I think the biggest missing piece in what's currently there is the
section on repetition above.

I would also suggest that if Edward has gotten a grip on some of the
library, he could start a Wiki page based on this model which could
eventually be turned into official library documentation.

-- 
                       David Abrahams
   dave_at_[hidden] * http://www.boost-consulting.com
Boost support, enhancements, training, and commercial distribution