RE: [boost] Preprocessor Docs Comments

From: Paul Mensonides (pmenso57_at_[hidden])
Date: 2003-10-14 05:27:51

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

I'll go into this in more detail:

> I've been reviewing some code [1], and wondered if there was
> something in 
> Boost to save having to write out the convenience functions 
> by hand. It 
> seems the Preprocessor library is what I need, but after 
> reading the docs 
> I'm confused as to how to go about using it.

The library is effectively a programming language.  There is no simple
answer for the question "how to use it."  However, there are examples
that use the library to do various things, but they, by no means, cover
the gamut of possible uses.  Hence, the documentation on each element of
the library shows what each element of the library can do (there are
many).  How you put those together is up to you.  However, the learning
curve is inherent--just as it is with any programming language.  You
have to get to know (at least some of) the language through
experimentation before you can use it to solve your real problems.

> Here is some (hopefully constructive) feedback on the docs,
> ranging from 
> important to petty:
> 
>    1. /libs/preprocessor/doc/index.html
>       There is no explanation or introductory text. In fact I
> looked at this 
> page and thought the docs had not been written yet and just 
> the headers and 
> been placed ready. But just to see if it was a Mozilla issue 
> I checked the 
> source and discovered the they were actually links. Specifics:

This is the what the documentation needs most--an introductory text.

>       a) Use conventional blue for links
>       b) Explain what will be found in each section, even
> with just a sentence.
>       c) Paragraph at the top of this page explaining what 
> the preprocessor 
> library is.

A relatively primitive and strange programming language built atop Cpp.
:)

>    2. /libs/preprocessor/doc/topics.html
>       Should use same layout style as first page (i.e. first
> page is black 
> text, this page is grey text with bullets; needs consistency).
> 
>    3. Generally for HTML titles, I think
> "Boost.Preprocessor:Topics" is 
> better than "topics.html".

It does have a consistent layout and style.  Both of these two issues
are the result of viewing the page outside of the frame where it
normally goes.  This is fine and doesn't harm anything, but then you get
the title issue and the style may not appear as uniform.

>    4. /libs/preprocessor/doc/topics/motivation.html. In the
> "The Motivation 
> Example Revisited" section I wanted to know:
>       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.

>       b) A breakdown of what each line is doing (or links to
> the reference 
> docs for each Boost macro used)

Yes.

>       c) If "MAX_IS_FUNCTION_TESTER_PARAMS" is required, or
> if 15 can be 
> directly embedded, e.g.:
>         BOOST_PP_REPEAT(BOOST_PP_INC(15), IS_FUNCTION_TESTER, _)

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.

>      If the example had been built up in two or three steps
> it would have 
> helped (I don't understand the library enough to know if any 
> intermediate 
> steps are possible however).

There isn't much to the example.  Especially if you look at the
reference documentation for each primitive used--they are pretty
straightforward.  The library is simply too large to explain the meaning
of everything used in examples inline.  The intent of the example here
is not to show how to do XYZ, but rather to show that XYZ can be done.

>    5. /libs/preprocessor/doc/topics/incompatible.html
>      Refers to 1.28 as the previous release. Maybe this page
> can be dropped now?

Yes, probably.

>    6. /libs/preprocessor/doc/topics/techniques.html
>      This page badly needs an introductory paragraph stating
> what it is all 
> about. I assumed it was going to show me the various ways you 
> can use the 
> library to simplify your code. But it is defining macros that 
> start with 
> "BOOST_" so is this explaining how the library was written?

This is an artifact from before my time.  BOOST_PP_DEF is used as some
arbitrary user-defined macro.  Personally, I don't think anyone should
ever define BOOST_PP_ prefixed macros unless it is specifically required
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.

>      The second example is supposed to show use of
> "BOOST_PP_EMPTY" but the 
> example only uses (well, defines, not uses) BOOST_PP_DEF.

I thought I fixed this one already.  E.g. the idea is:

#define MACRO(id, cv_qualifier) cv_qualifier() int id;

MACRO(x, const BOOST_PP_EMPTY) // const int x;
MACRO(y, BOOST_PP_EMPTY)       // int y;

>      It would be helpful if all examples showed the code that
> they generated 
> so the two can be compared side by side.

Maybe in some cases, but the documentation also needs to encourage
experimentation.  There are literally hundreds of examples in the
documentation.

>    7. The reference page is intimidating - can it be broken
> down into sections?

I assume that you're referring the index of macros.  It could be broken
down a little bit, but that would decrease its utility.  (It's just an
alphabetical index of library primitives.)  The headers section is
broken down in a more logical fashion (though it is also a
reference-like section).

>    8. I think my comments for 4, 6, and 7 are because there
> is no page that 
> leads me from "here is my old code" to "here is how you'd use 
> this library 
> to rewrite it".

That is because the library is a programming language.  It is not a
simplistic input -> output tool--the primitives are too low-level for
that.  There is a learning curve, and there is a degree of lateral
thinking involved.  However, the library is powerful (despite the fact
that it has its hands tied by buggy--but popular--preprocessors), but
the learning process is not a simple sequence of linear steps.  It isn't
overly difficult to learn either.  (I know because I did it myself at
one point.)  If you want to learn it, go through all of the macros in
the reference section and experiment with them.  This will give you a
good idea of what's in the library and what you can do with it.  It will
also give you a degree of familiarity that just reading documentation
won't.  That degree of familiarity is the foundation for the lateral
thinking required to actually solve real problems in the future rather
than toy examples used to experiment.

That said, the documentation definitely needs improvement.  The most
important things that it needs are a simple introductory section and a
general outline of what broad categories of facilities are available.
(I have a big list of improvements that I need to make.)

Regards,
Paul Mensonides