[boost] Re: Some remarks on PP docs

From: Vesa Karvonen (vesa_karvonen_at_[hidden])
Date: 2004-06-10 13:32:47

>techniques.html:

Since I initially wrote the document, I might as well comment.

>I was really confused by the use of the word "standard".  This would
>be clearer:
>
>   It is usually okay to reuse a single generic macro name like
>   BOOST_PP_DEF throughout your code because the macro is both defined
>   and undefined very close to its point of use.

Yeah, there is probably a better way to convey the idea.

>Although I don't know why you'd want to advocate that over using a
>descriptive name.

Because those macros are essentially [used like] lambda expressions: ad
hoc, short, local functions that you usually do not even want to name.

There is also an additional benefit of using a single generic name. If you
forget to write the #undef, you will more likely get a warning (or an
error) from the preprocessor. #undefining local macros helps to avoid
macro replacement related problems.

>A clearer divider between examples would be a *huge* help visually.
>An <hr> would be enough, for example.

Looking at an old revision in CVS, this used to be the case.

>?? Where is BOOST_PP_EMPTY used in this example?  I think I know what
>you mean, but really, you need to show it!

Looking at old revisions in CVS, it used to be there (use of
BOOST_PP_EMPTY).

>   Note:  BOOST_PP_EMPTY with the () never gets expanded.
>
>This sounds self-contradictory.  Just above you said it expands (to
>nothing)!

Again, looking old revisions in CVS, it used to read "without".

>   The () is necessary to invoke a function-like macro.
>
>No duh; I think stating the obvious that way only adds confusion.

Perhaps. The point is to point out the reason why the macro does not get
expanded. The idea of passing the "name" of a function like macro as a
parameter may not be obvious to all.

>   Caveat:  You cannot safely use concatenation while using 
>BOOST_PP_EMPTY().
>
>That's way too vague and general.  I certainly can use concatenation
>and BOOST_PP_EMPTY "together", for many reasonable definitions of that
>word!  I think you need to be more specific, or strike it.

Agreed.

>The BOOST_PP_ENUM_PARAMS example could benefit greatly from a
>side-by-side format in a table showing the expansion on the right.

There used to be a page that contained all the examples of the tutorial
after preprocessing (and formatting). You could then simply click the
title of the example to see the preprocessed code.

>Showing not-even-correct details of BOOST_PP_REPEAT's implementation
>doesn't help here.  I'd strike it.

You are probably right. I suppose when I wrote that, I wanted to give an
idea to the reader how such macros might be actually be implementable (so
that it doesn't seem as magical as it otherwise might). Looking back, I
think that it was a mistake, because I have seen several people inventing
their own REPEAT-style macros rather than using the generic macros in the
library. Although, it might be the case even if the tutorial were
different (nothing would have prevented those same people from looking at
the actual implementation and learning the same information).

>Furthermore,
>
>   BOOST_PP_ENUM_PARAMS and its variations use BOOST_PP_REPEAT.
>   BOOST_PP_COMMA_IF(I) expands to a comma if I != 0.  BOOST_PP_INC(I)
>   essentially expands to "I+1," and BOOST_PP_DEC(I) essentially
>   expands to "I-1.".
>
>I'd strike that too.  You haven't said a word about BOOST_PP_INC/DEC
>yet, so the reader is left wondering why you're giving their
>implementation details.

I agree that the comment should be removed. I think that the comment has
probably been more relevant at some stage (CVS would probably reveal it
if this was the case), but the context was lost during editing. That
''BOOST_PP_DEC(I) essentially expands to "I-1"'' is hardly an
implementation detail.

>Is this really better than iterating over a SEQ of categories in any
>way other than efficiency?

At the time when the example was written, SEQ had not yet been invented
and even lists were not as efficient and convenient as they are today.
Unfortunately, the example was never updated. Today, I would generally
advocate using a sequence (or some other data structure).

>   Example - Use BOOST_PP_REPEAT to avoid O(n*n) repetition.
>
>It's unclear to me how that example avoids O(n*n) repetition.

The point is to avoid manual, source code time, repetition and replace it
with automated, preprocessing time, repetition. The code that you will
edit after using REPEAT will be only O(1) (and not O(n*n)).

It is the same as using a high level language to avoid programming in
machine language. Sure, the compiler translates the high level code to
machine language (well, not exactly, but close enough), but this doesn't
mean that (because of the translation) you would not be avoiding
programming in machine language as you seem to suggest.

>   Example - Use BOOST_PP_REPEAT for O(n*n) repetition.
>
>Or something?

That might be a better way to convey the idea.

>   BOOST_PP_IF enables convenient generation of lists using
>   BOOST_PP_REPEAT.
>
>This statement, without an example, is too vague to be helpful.

I agree.

>Implementation details of BOOST_PP_IF don't help:
>
>   How:  BOOST_PP_IF is defined for the entire repeat range (psuedo code):  
>  #define BOOST_PP_IF(c, THEN, ELSE) BOOST_PP_IF ## c(THEN, ELSE)
>
>   #define BOOST_PP_IF0(THEN, ELSE) ELSE
>   #define BOOST_PP_IF1(THEN, ELSE) THEN
>   #define BOOST_PP_IF1(THEN, ELSE) THEN
>                      ^
>especially since they appear to be wrong.

Again, looking at an old version in CVS, this used to be correct.

>I think the point is that BOOST_PP_IF works on first arguments other
>than 0 or 1.  If so, you should just say that it works on numeric
>arguments up to N (whatever N is).

That is probably a better way to put it. Again, the idea was to show how
IF might actually be implemented (to dispell the magic), but it was
probably a mistake.

>   Example:  Use arithmetic, logical, and comparison operations when
>   necessary.
>
>With no commentary, and no generated code, this example is really
>useless.  I mean, of course you'd use arithmetic, logical, and
>comparison operations "when neccessary".

Looking at an old [...], there used to be a comment:

  "<P>The PREPROCESSOR library supports saturated arithmetic, logical
   and comparison operations on decimal integer literals in the range
   [0,BOOST_PP_LIMIT_MAG].</p>

   <p>Suppose that you want to generate a numbered lists with a special
      element inserted at a desired position. For example: E0, E1, S, E2.
      Consider the following example:</p>"

The point of the example was really just to let the reader know that the
library does contain macros for arithmetic, logic, etc...

The example is admittedly weak and only designed to use some of the
mentioned classes of macros.

-Vesa Karvonen

_________________________________________________________________
The new MSN 8: advanced junk mail protection and 2 months FREE* 
http://join.msn.com/?page=features/junkmail