Boost logo

Boost Users :

Subject: Re: [Boost-users] [mutli_index] class reference available? / How to detect insertion failures
From: joaquin_at_[hidden]
Date: 2008-10-10 04:10:26

Hello Nick,

First of all, thank you for trying Boost.MultiIndex despite your
struggle with
the documentation. My opinions on the issues you raise are below.

Nick Martin escribió:
> Adam,
> Thank you for your quick reply. I had looked at the particular page
> that you
> reference, but was confused by its contents.
> I was confused by the reference documentation included with multi_index
> for a few reasons.

The reference layout mimics that of the C++ standard, which is
admittedly not
the user-friendliest around, but has the virtues of being very precise,
towards concept description rather than member function description and,
standard. It takes time getting used to, but once you know how to use it
you can
rest assured all the information you need is in there and is not
particulary hard
to find.

For a feel of how the C++ standard documentation looks like you can take a
look at

and, in particular, to chapter 23 (containers). The reference is
organized according
to the following scheme:

* General concepts and associated requirements (valid expressions,
exception-safety, etc.)
  + Concept refinements (for instance, associative container is a
refinement of
  container): valid expressions, complexity, etc.
* Header synopsis: Lists, in pseudo-source-code form, the particular
provided by the header. For each such component:
  + Component description: Concepts modelled and particularities.
  + Component synopsis: lists in pseudo-source-code form the member
  functions, types, etc. associated to the component.
  + Description of those member functions or aspects that are not implicitly
  covered by the concepts modelled by the component. This point is
  for instance, you can see in the description of std::list that
std::list::begin() and
  std::list::end() are not explicitly commented, because all that can be
  about them is already covered by the description of the concept
  Member descriptions are grouped (for containers at least) as follows:
    - member typedefs
    - constructors, copy and assignment
    - iterators
    - capacity
    - modifiers (memfuns changing the state of the class)
    - observers (memfuns not changing ths state of the class)
    - specific operations (ops not covered by the general concepts)
    - specialized algorithms (operator==, swap, etc.)
  The description of each member function covers the following aspects:
    - Argument requirements
    - Effects (side effects, changes in the state of the class)
    - Complexity
    - Exception safety
  If some aspect is not explicitly covered, some default is assumed: for
  is no explicit exception safety guarantee is given, basic safety is

Another thing you might find interesting to bear in mind is that the
at least in the form provided by Boost.MultiIndex, is *not* the primary
to learn what the lib is about or how its general usage is: this is
by the tutorial. The reference is meant to be used for finding *exact*
about the components provided, once you have a general feel for the
library. To draw an analogy, tutorial and reference play the same roles as
an english textbook and a dictionary do in the context of language
teaching: you don't learn to speak English by diving head-first into the

> My main points of confusion came from:
> * Reference pages have no introductory text -
> doesn't say what a hash index is, what it is used for, etc. The
> main reference page is
> especially terse

The description of what a hased index is is given here

which follows the general outline described above: component description,
after header synopses.

The main reference page is merely a directory to other sections, each
devoted to
a different concept and/or component.

> * Header file "synopsis" - it is probably lost on me, but why are
> excerpts of the source code included?

Hopefully explained above.

> * Large amount of source code inclusion - as a user of the library
> I haven't found
> the inclusion of portions of the headers particularly helpful. I
> am sure that there
> is a good reason for them to be there, but why not just have a
> simple line or two
> stating that a particular header is required for certain situations?

Hopefully explained above: this pseudo-source-code is a terse way to
list all the
relevant pieces (types, member functions, specialized functions)
provided by the
component being documented.

> * Font usage - why are "Effects" "Returns" "Complexity" in the
> same size (or very similar size) font as "Modifiers"? It took my
> eye away from the actual method names, which is what I was
> looking for.

Oh. Well, the clauses "Effects", etc. are within a <blockquote> tag and
should have an
indentation making them easy to distinguish from "Modifiers" etc, which
are section
headers and appear without indentation. Do you see otherwise in your

> * Why are the constructors, method names, etc so far down the page
> (six
> page downs on my computer)? It seems like that is the
> information that is most
> helpful/searched for.

Once you understand the general layout, it is not hard to locate what
you want.
For instance, if I want to consult the constructors of
I know I have to find them within the description of this class, under
the section
"constructors, copy and assignment". In fact, the contents of
multi_index_container reference provides fast access to that section:

> Now that I understand what I am looking at a little bit better, it
> does look like
> multi_index does follow the same outline as some other boost libraries
> (like bimap).

Well, Boost.Bimap is designed on top of Boost.MultiIndex, and the docs
from the
latter heavy influence the former.

Besides, other Boost libs follow this same convention. Take a look at
the following

> That said, multi_index still looks like it has a way to go to catch up
> with some
> other libraries (Asio and Tuple, for instance), which I find much
> easier to use
> and understand.

The ones that you mention are certainly superb libraries and I don't want to
contend about whose docs are better. But I certainly think that the C++
std style
is very well suited to a form of documentation that is not so easily
with Oxiygen and other annotation tools: the latter tend to focus on
each member function in isolation and favor the repetition of
descriptions, while
the C++ std way focus heavily on concepts: in fact, one can say that
are the primary part of a reference, and only departures from /
extensions of the
concepts are explicitly annotated.

I also think that the more you get acquainted with this style of reference
documentation the better you'll like it.

> I can see from the boost-users archive that documentation standardization
> has been an issue for a while (goes back to at least 2005).

Unfortunately, I don't think an agreement about documentation style (as in
exposition style, not visual layout) has been achieved. The only guide
we got in this
respect are the minimal indications given at:

> I also realize that this is free software and the documentation is
> what it is.

I know there's a feeling that open source is generally lacking in the
area of documentation,
but in this particular case I can assure you that documentation has been
given prominent treatment right from the start. This might be open
source software,
but I've spent many hundreds of hours in it and my (unmodest) goal is
that its quality be
second to none (commercial sw included) in all aspects, including
documentation. Matter
of fact, more time has been invested in documentation than actual coding.

And I take all suggestions and criticisms very seriously. I'm not
dismissing your
complaints but trying to understand them better and, hopefully, address
them in a
satisfactory manner.

> As a user that is used to documentation from other vendors and other
> styles
> (JavaDoc, DoxyGen, MSDN library), this documentation is severely lacking.
> That is a shame because I think that multi_index itself looks like a
> great library
> that should be used by as many developers as possible.

Joaquín M López Muñoz
Telefónica, Investigación y Desarrollo

Boost-users list run by williamkempf at, kalb at, bjorn.karlsson at, gregod at, wekempf at