[boost] Preprocessor Docs Comments

From: Darren Cook (darren_at_[hidden])
Date: 2003-10-14 03:23:08

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.

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

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

   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.
      b) A breakdown of what each line is doing (or links to the reference 
docs for each Boost macro used)
      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, _)
     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).

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

   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?

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

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

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

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

If anyone wants to take my below example and show be how I'd use 
Boost.Preprocessor to simplify it I'd greatly appreciate it. Maybe it could 
then be copied and pasted directly into a FAQ page of the docs :-).

Darren

[1]: I have a class containing these functions:
  void add_ifthere(int d,int v){
   /* Do something */
   }

  void add_normal(int d,int v){
   /* Do something */
   }

  void add_only(int d,int v){
   /* Do something */
   }

And then the same class has some convenience functions:
  void add_ifthere(int d1,int v1,int d2,int v2){
   add_ifthere(d1,v1);
   add_ifthere(d2,v2);
   }

  void add_ifthere(int d1,int v1,int d2,int v2,int d3,int v3){
   add_ifthere(d1,v1);
   add_ifthere(d2,v2);
   add_ifthere(d3,v3);
   }

//Same thing for add_normal and then add_only
//Efficiency is important so I don't want to use variable-args.