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_ind... 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.ht....
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_ind... 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.ht...
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