RE: [boost] Preprocessor Docs Comments

From: Paul Mensonides (pmenso57_at_[hidden])
Date: 2003-10-14 13:34:11

> From: boost-bounces_at_[hidden] 
> [mailto:boost-bounces_at_[hidden]] On Behalf Of Darren Cook

> I guess I'm after the "O'Reilly Boost.Preprocessor Cookbook" 
> in that case :-).

Yeah, the problem is that a full explanation of the library requires in
depth coverage of preprocessor metaprogramming--and that is book.

> > It does have a consistent layout and style.  Both of these 
> two issues 
> > are the result of viewing the page outside of the frame
> 
> Sorry I didn't think about that - I tend to open most links 
> in a new tab. I 
> still think frames should have descriptive titles though. 
> Also useful for 
> search engines.

At some point, I'm going to redo all of the documentation, but I'm going
to generate it with XSLT and pull it out of the frames.  That will make
it fairly easy to change things like style and layout and making global
changes like titles.

> >>      a) What feature each of the three headers is loading in.
> > 
> > <inc.hpp> brings in BOOST_PP_INC, <comma_if.hpp> brings in 
> > BOOST_PP_COMMA_IF, and <repetition.hpp> brings in 
> BOOST_PP_REPEAT and 
> > BOOST_PP_ENUM_PARAMS.  These things should be self-evident though.
> 
> Yes, I worked out three, but BOOST_PP_ENUM_PARAMS is 
> non-obvious. I just 
> wanted more hand-holding as this was the first example I'd come to.

Okay, I understand.

> > Yes, it can be.  However, the intent is to make the code expand to 
> > some arity specified elsewhere as a configuration option. 
> > MAX_IS_FUNCTION_TESTER_PARAMS is just used for a default value.
> 
> In that case maybe that is the intermediate step I was 
> suggesting - first 
> with 15 hard-coded (keeping the example shorter and less 
> intimidating), and 
> then a revision to show how to use a configuration option and 
> supply a default.

Yes, that makes sense.

> > by a library element.  Also, I don't recommend using all-caps 
> > identifiers for *temporary* macro names--using all-caps 
> here actually
> > *increases* the likelihood of a name conflict.
> 
> Interesting - it seemed very strange however to see 
> lower-case defines in 
> your example. I'm not sure I could get used to that!

Any macro that is permanent should use an all-caps name.  Further, any
macro that is part of a library should use a prefixed all-caps name.  A
temporary macro, e.g. one used for local code generation such as:

#define SPEC(type) // ...

SPEC(A)
SPEC(B)
SPEC(C)

#undef SPEC

...is more likely to clash with an existing permanent macro if it uses
all-caps.  It is better in this case, IMO, to use a lowercase or
mixed-case identifier--if and only if the macro is immediately
undefined.

#define spec(type) // ...

spec(A)
spec(B)
spec(C)

#undef spec

Regards,
Paul Mensonides