[boost] Re: Preprocessor doc

From: Vesa Karvonen (vesa_karvonen_at_[hidden])
Date: 2002-04-17 02:05:59

I accidentally hit the Send button (I'll have to blame the sorry excuse for
a mouse on my laptop for that), so I'm filling the missing stuff now...

David Abrahams:
> 1. I think it would be a lot clearer if the names of formal parameters
> to macros were not ALL_UPPERCASE. A little variation helps to
> distinguish what's going on, and, after all, there's no reason to use
> ALL_UPPERCASE for macro params (is there?)

I suppose that some of the examples could be more readable if formal
parameters, actual parameters and library macro names were decorated
differently (whenever it is possible). I'll see how it turns out.

There is no technical reason to use all uppercase for macro parameters.
However, I prefer it because, IMO, it makes macro definitions containing C++
code easier to read. Since C++ code doesn't contain all uppercase
identifiers, it is much easier to spot where the macro parameters, or other
macros, are used. In other words, it makes the variation points visible.

> 2. Callable macro args should probably be called "function", not
> "MACRO", since the former describes how they act in the lib context and
> since there are non-function macros.

MACRO is currently used for parameters that are directly used for producing
output (C++ code) from a (higher order) macro. For instance,
BOOST_PP_REPEAT() takes a MACRO as does BOOST_PP_FOR(). BOOST_PP_FOR() also
takes two more function like macros as parameters (PRED and OP), but those
are not used for producing output. The reason why I chose to use the name
MACRO, is because it corresponds, more or less, to the traditional intention
of preprocessor macros: to produce C[++] code.

I suppose MACRO isn't the best name, but "function" isn't much better
either. A better name should emphasize the intention of the parameter (not
just the type like "function"). In the documentation I also describe MACRO
as a "state instantion macro". Anyway, I currently don't have a better name.
I'd like to hear more suggestions.