Re: [Boost-users] [mutli_index] class reference available? / How to detect insertion failures

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, 
oriented
towards concept description rather than member function description and, 
well,
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

http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2691.pdf

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

* General concepts and associated requirements (valid expressions, 
complexity,
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 
components
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 
important:
  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 
said
  about them is already covered by the description of the concept 
"container".
  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 
instance,
  is no explicit exception safety guarantee is given, basic safety is 
assumed.

Another thing you might find interesting to bear in mind is that the 
reference,
at least in the form provided by Boost.MultiIndex, is *not* the primary 
source
to learn what the lib is about or how its general usage is: this is 
accomplished
by the tutorial. The reference is meant to be used for finding *exact* 
information
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
Merriam-Webster.

> My main points of confusion came from:
>
>     * Reference pages have no introductory text -
>       http://www.boost.org/doc/libs/1_36_0/libs/multi_index/doc/reference/hash_indices.html
>       doesn't say what a hash index is, what it is used for, etc. The
>       main reference page is
>       especially terse
>       http://www.boost.org/doc/libs/1_36_0/libs/multi_index/doc/reference/index.html.
>
>

The description of what a hased index is is given here

http://www.boost.org/doc/libs/1_36_0/libs/multi_index/doc/reference/hash_indices.html#hash_indices

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 
browser?

>     * 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 
multi_index_container,
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:

http://www.boost.org/libs/multi_index/doc/reference/multi_index_container.html#synopsis

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

http://www.boost.org/doc/html/array/reference.html
http://www.boost.org/doc/html/any/reference.html
http://www.boost.org/doc/html/function/reference.html

> 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 
attainable
with Oxiygen and other annotation tools: the latter tend to focus on 
documenting
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 
concepts
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:

http://www.boost.org/development/requirements.html#Documentation

> 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