Boost logo

Boost :

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


[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){

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

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

Boost list run by bdawes at, gregod at, cpdaniel at, john at