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: Nick Martin (nick_at_[hidden])
Date: 2008-10-10 14:13:15

Hello Joaquín,
Thank you for explaining the documentation. I appreciate your hard work and
dedication to the docs. I do think that it is unusual for an open source
project to have such emphasis placed on its documentation.

In the spirit of getting feedback out there, please allow me to challenge a
few things. I don't mean this as criticism of you personally or any other
boost contributors; I'm just trying to help.

The tutorial and examples provided for multi_index are good. That is where I
started and I was able to learn a lot from them. I totally agree with your
learning English/dictionary analogy.

It was when I tried to go beyond the material covered in the tutorial and
examples that I started getting frustrated. That's when I went looking for a
reference and that is what led to my first post. A reference that was more
easily browsable by class and method like JavaDoc, the Asio libraries,
Doxygen and MSDN would be extremely helpful. As it is today, one must do a
lot of clicking and scrolling to get to a particular method description with
its paramaters and return value.

Patterning the multi_index reference documentation on the C++ standard docs
certainly has some good logic behind it, but who looks something up in the
C++ standard when they need to figure something out about C++? My guess is
that it is not the typical C++ user. Everyone that I know refers to other
reference materials. The C++ standard is certainly important if someone is
trying to write a C++ compiler or a new implementation of the STL. So to me
it seems like the C++ standard docs are most helpful to someone who is
trying to *follow* or *implement* the standard, not *use* the standard. It
seems like the boost library reference documentation is used mostly by
people who are trying to *use* the library since the implementation is
already done -- it's the header files themselves. From a user perspective,
it seems like the documentation is patterned on an example that is
suboptimal.

In short, I think that a reference that was searchable and browsable by
class name, type name, method name, etc would be much quicker and easier to
use for the typical multi_index user.

Thanks,
Nick

On Fri, Oct 10, 2008 at 1:10 AM, <joaquin_at_[hidden]> 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.
>
>  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
>
> _______________________________________________
> Boost-users mailing list
> Boost-users_at_[hidden]
> http://lists.boost.org/mailman/listinfo.cgi/boost-users
>