Re: [boost] Preprocessor Docs Comments

From: Gregory Colvin (gregory.colvin_at_[hidden])
Date: 2003-10-14 09:18:03

On Tuesday, Oct 14, 2003, at 04:27 America/Denver, Paul Mensonides 
wrote:

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

Right.  And I would find it easier to understand if I could study its 
BNF grammar.

>   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
>
> _______________________________________________
> Unsubscribe & other changes: 
> http://lists.boost.org/mailman/listinfo.cgi/boost