[Boost-users] Request for generalized `overview' documentation

Subject: [Boost-users] Request for generalized `overview' documentation
From: tom fogal (tfogal_at_[hidden])
Date: 2009-07-05 18:10:22

Hi all, I'd like to put in a request for an additional kind of
documentation to be distributed with boost.

Current boost documentation, I would argue, is very good at answering
questions of the form, 'How can I get Boost.X to do functionalityA?'
It is not so good at answering the question, 'How can I obtain
functionalityA?'

To make a long story (somewhat) short, especially when one wants to do
something relatively simple and limited, many boost libraries might
be able to fill the role.  Today's problem is providing a callback
mechanism.  A simple freestanding function would work fine.  Yet at
some point, I know somebody is going to wish they could pass a member
function, and then someone else will want to pass any object that
implements operator(), and then ...

There are multiple libraries which I might use to fulfill this goal.
What's lacking is a way to (quickly!) figure out which one I want.
>From limited skimming, it seems like Boost.Function might do what I
want.  However, I might consider that a future use case would allow
multiple functions to get called from a single callback `site',
which would cause me to choose Boost.Signals.  If I'm concerned with
thread safety, it seems like I might choose Boost.Signals2.  I think
Boost.FunctionTypes might fit in here somehow too, but I'm still not
sure.

In this case, I'm concerned with compilation time, but execution
time is not likely to be important.  It seems like the only way I
could determine which library fits best given that restriction is to
implement a few simple programs.

Given today's inquiry, a short blurb like the following would go a long
way:

  Boost.X grew out of frustrations implementing nitz-frobbing in
  terms of Boost.Y.  Along the way, it was discovered that X provided
  a natural vehicle for standardizing foo-like syntax such that
  compile-time errors could be generated in the bar case.

  The price paid for the ability to easily frob your nitzes is memory.
  X must store 16 additional words of state for every nitz to guarantee
  an O(log n) traversal of a nitz-holding container (it's actually
  2*log n due to the requirement of identifing the internal node with
  the highest stitzel before the frobbing can start).

  Note: Boost.Z provides an alternative methodology for foo-ing which
  adheres to the SomeConceptA protocol (which X does not).

There's an incredible amount of useful information here.  If Boost.Y
looked relevant before, I could presumably decide if I should go
with that based on whether I think I'll need to frob the nitz in
the future.  Presumably looking at the 30-second blurb from Y and Z
would let me reason out which library I would want for foo-ing.  The
performance characterization gives the information I need to choose
between implementations with a good O() versus, say, implementations
which will fit all of my nitzes in cache on my most important platform.

You might also think of an alternative form, which categorizes Boost
libraries and provides a `category introduction' to overview them.
Given the somewhat distributed nature of Boost libraries, I figure a
blurb per library is easier, but from a user's perspective I'm not
convinced it matters.

Thanks for reading,

-tom