[boost] Some remarks on PP docs

From: David Abrahams (dave_at_[hidden])
Date: 2004-06-10 11:27:44

techniques.html:

  It is usually okay to use a standard macro name like BOOST_PP_DEF
  for this kind of code because the macro is both defined and
  undefined in the immediate site of its use.

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.

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

------

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

  Example - Use BOOST_PP_EMPTY as an unused parameter in local macro instantiations.
  #define BOOST_PP_DEF(cv) /* ... */ \
     template<class base>            \
     cv() typename implement_subscript_using_begin_subscript<base>::value_type& \
     implement_subscript_using_begin_subscript<base>::operator[](index_type i) cv() { \
        return base::begin()[i];     \
     }                               \
     /**/

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

  How:  BOOST_PP_EMPTY() expands to nothing and can be used as an
  unused parameter. 

  Note:  BOOST_PP_EMPTY with the () never gets expanded.  

This sounds self-contradictory.  Just above you said it expands (to
nothing)!

  The () is necessary to invoke a function-like macro.

No duh; I think stating the obvious that way only adds confusion.

  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.  

------

The BOOST_PP_ENUM_PARAMS example could benefit greatly from a
side-by-side format in a table showing the expansion on the right.
In fact, that would help all the examples, but in particular if
you're just getting acquainted with the library at this point you may
not have any idea what some of those macros do.  You're advocating
that people use them here, but unless the reader has some idea of what
they generate, it's lost on her.

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

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.

-----

  Example - Use BOOST_PP_REPEAT and a token look-up function to
  eliminate categorical repetition.

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

-----

  Example - Use BOOST_PP_REPEAT to avoid O(n*n) repetition.

It's unclear to me how that example avoids O(n*n) repetition.  It
certainly seems to have that complexity, and that appears to be
intrinsic to the code it generates.  Maybe you mean 

  Example - Use BOOST_PP_REPEAT for O(n*n) repetition.

Or something?

-----

  BOOST_PP_IF enables convenient generation of lists using
  BOOST_PP_REPEAT. 

This statement, without an example, is too vague to be helpful.

-----

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.  

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).

---------

  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".

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com