[boost] Re: Re: Boost preprocessor library

From: Edward Diener (eddielee_at_[hidden])
Date: 2003-01-14 10:40:35

"Paul Mensonides" <pmenso57_at_[hidden]> wrote in message
news:000701c2bba1$dbb07aa0$7900a8c0_at_c161550b...
> ----- Original Message -----
> From: "Edward Diener" <eddielee_at_[hidden]>
>
> > I see many pre-processor macros in the reference section of the
> > documentation but I don't see any good overview explaining the various
> > macros or groups of macros and the ideas behind them.
>
> The directory groupings of the library's headers are a pretty obvious clue
> for most of the preprocessor library (e.g. directory names such as
> "arithmetic" and "repetition").  While there is no "general overview" for
> the time being, you can look at the directory structure (which is included
> in the documentation) and get a pretty good idea of what is in the
library.
> The library includes facilities for arithmetic, logical, and comparison
> operations, repetition constructs (horizontal and vertical), control
> structures (such as "if" and "while"), manipulation of several data types
> with unique properties, and a myriad of miscellaneous tools and facilities
> to help with using the afore mentioned groups.
>
> > What I am looking for
> > is a good overview of what macros are in the library. One section shows
> > examples, but they seem very random and don't seem to explain
> functionality
> > or ideas very well.
>
> Nearly every reference document for a particular macro includes a simple
> example.  The examples in those parts don't usually do anything incredibly
> useful.  They just exist to show how the respective macro *can* be used.
> There is no set group of domains to which the pp-lib caters.  You use it
to
> do whatever it is that you want to do.  (The pp-lib does, however, excel
at
> repetition.)  Many of the facilities in the library are similar to the
> low-level capabilities of a regular old "if" or "while".  Discussing at
> length what constructs like this are good for would only complicate the
> documentation even more than it already is.  The documentation provides a
> reference of all macros (etc.) in the library and shows how to use them.
> How you use them and what you use them for is up to you.
>
> If you have a specific question or a general idea of what you want to
> accomplish, you can always ask me.  I can point you in the right
direction,
> give you advice, and tell you if it can or cannot be done.
>
> Dealing with the preprocessor as a programming environment is like
learning
> a whole new language--one that doesn't even have many language features
that
> are taken for granted (i.e. arithmetic, looping, flow control, etc.), so
you
> have to expect that it takes some experimentation and experience to
> understand it.  I will help you in every way that I can.
>
> > The preprocessor library would be much more understandable if the ideas
> > behind the macros were discussed and if an overview allowed end users to
> > understand what is in the library.
>
> The fundamental reason that the library is inaccessable and has such a
step
> learning curve is that the library is not written in C++ (or even C).  It
is
> written in Cpp.  Furthermore, it is like any other library written to be
> used by a specific language.  You must have a reasonable understanding of
> the language in order to use the library.  This requires more than a
minimal
> conceptual understanding of Cpp, but a nitty-gritty
> "what-happens-when-and-what-doesn't-happen-and-why".  That is what makes
it
> steep.
>
> I agree that the documentation can be improved considerably, but that is
> also a massive undertaking.  Consider the available documentation on C++
> idioms.  The literature is spread over thousands of books, articles, and
> decades of algorithmic lore.  The available literature for programming in
> Cpp is largely confined to one place (that I know of), and that is the
> documentation for Boost's pp-lib.  I am certainly not saying that Cpp is
on
> par with a general purpose programming language (such as C++) as far as
the
> raw number of unique idioms, but it has great many nonetheless, and the
> primary purpose of the documentation is to describe the library, not the
> language.

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.