On Fri, Oct 10, 2008 at 1:10 AM,
<joaquin@tid.es> wrote:
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.
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