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 M Lopez Munoz (joaquin_at_[hidden])
Date: 2008-10-12 11:16:43

Nick Martin <nick <at> transdigita.com> writes:

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

Of course, I never thought otherwise. Rereading my previous answer I
realize it might sound harsher than actually meant: sorry for that,
I truly appreciate critique and never took your comments as
offensive or flaming.

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

My main objection against by-member documentation as typically
produced with JavaDoc and other annotation tools is that they
shift the focus from general concepts, which C++ happens to
rely on more and more. Let me exemplify my point: consider
the case where we are documenting an iterator class:

  template<typename T>
  class my_container{
    class iterator;
    ...
  };

Using the C++ std style, one can simply say:

  "my_container<T>::iterator is a random-access iterator on
  elements of my_container<T>."

or something to that effect. Using by-member documentation,
one can easily end up having something like:

  iterator& operator++();
    effects: blah blah
    return: *this;
    blah blah

  void ++operator(int);
    blah blah

  value_type& operator*()
    blah blah

  [same for decrementing, random-access, addition, subtraction, etc.]

How's this more useful than simply stating that the iterator
is random-access? Of course this is an extreme example, but
hopefully you get my point: I think it's more useful, and
ultimately easier for the reader as well, to rely on concepts
as much as possible and avoid by-member repetitious annotations
when a reference to a concept suffice. I admit there can be
an entry barrier for those readers who expect an easily
browsable list of members for each class, but in the end
my hope is that the change of style to concept-based documentation
pays off, as the iterator example hopefully shows.

On the other hand you certainly have a point that the reference
underlying philospohy is not ovious. I remember when I first met this
style of documentation that it took me some wrapping my head around it
until I began grasping what it all was about. It doesn't help that
this underlying philosophy is not explained anywhere, neither in the
standard text nor in Boost. Do you think having some support article
in Boost, something along the brief guideline I gave in my previous post,
would help overcome these usability problems?

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

I do not agree that the standard documentation is
particularly aimed at implementers rather than users: in my opinion,
the reference is a *contract* between the user and the implementer,
and as such both parties have equal interest in understading it
thoroughly.

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

I can try to lower the entry barrier by decorating the names
appearing in the component synopses with links to the relevant
sections, (much as other Boost libs already do). The problem with
this is: what to do with those names that are not explicitly
documented because they're covered by concepts (like begin, end, etc)?
Do I simply leave them unlinked?

> Thanks, Nick

Thank you for your comments,

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