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-14 18:47:14

Hello Joaquín,
Please see my comments below

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.

Just to make sure that I understand, you object to automated documentation
tools in particular because they produce output that:

1. doesn't focus on concepts (e.g. too low-level includes things like
operator overloads and template details), they don't stay at a higher level
of abstraction
2. is repetitious

I understand those objections and I agree. I am not asking for totally
automated documentation per se - I just think that something that was
browsable by members would be very nice. It just so happens that automated
documentation tools can produce documentation that is very easy to navigate,
which I would love to have for multi_index. That is why I suggested it as a
starting point.

As an example of my frustration with the docs - say I want to look at the
ordered index's find method. With the docs, as is, starting from the
reference section of the docs (
http://www.boost.org/doc/libs/1_36_0/libs/multi_index/doc/reference/index.html)
I do the following:
1. click on "ordered indices"
2. I either know that find is a "set operation" (not obvious to me) and
click that link or I scroll down (page down key 12 times in my browser)
until I find it (or search within the page for "find"). If I didn't know the
name of the method, however, it would be quite time consuming and painful to
browse until I found the "find" method 12 pages down.
3. As I mentioned in an earlier post the fonts are difficult to read. The
method names themselves (seemingly the most important information on the
page) is in a font that makes it hard to find. Other parts of the text are
in bold or large fonts.

So basically the reference is only helpful if I already know the exact
method name I am looking for. I think that this is a shortcoming that other
documentation styles that I mentioned previously overcome quite nicely.

Today, there is no clickable set of method names at the top of the
reference. I think that is a big problem.

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

Perhaps. I think that this would overcome my initial problems with the
documentation, but I am concerned that there are fundamental problems that I
am having with the docs that go beyond a lack of understanding. Even now
that I understand how they are laid out they are frustrating to use, because
there is not an easy way to navigate through the docs.

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

I think that we may just have a fundamental disagreement here. It may be in
a user's best interest to understand the standard thoroughly. Then again, it
may not. Most people don't have the time, interest or need to understand the
standard thoroughly. They write software that is compiled for them by a
compiler. If they make a mistake the compiler tells them and they fix it.
They don't need to read the standard in order for that to happen. In fact,
it could be argued that for some, spending time reading the C++ standard is
definitely not in their best interest.
For instance, I don't need to know how my engine, antilock breaks, power
steering, etc in my car works to be a perfectly safe, competent driver. I
would argue that someone doesn't need to be thoroughly familiar with the
details of the C++ standard to be a competent coder.

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

I think a great example can be found in the MSDN STL documentation. I think
that they strike a nice balance between concepts (your stated aim) and the
ability to quickly navigate through the documentation and find information
on a particular class, method, type, etc (what I feel is missing from the
multi_index docs).

For instance the STL map class:
http://msdn.microsoft.com/en-us/library/s44w4h2s.aspx
>From that high-level page I can click on the "map members"
http://msdn.microsoft.com/en-us/library/xdayte4c.aspx and see at a glance
all of the member typedefs, methods, operators, etc. From this page I can
click on a member and get more detailed information. For instance, I can
click on the "begin" method and see its return type, etc and even an example
program showing it in use (
http://msdn.microsoft.com/en-us/library/kweswzhx.aspx).

There are many other examples of documentation out there that do similar
things.

I think that this style of documentation accomplishes what we both are
seeking - easy to navigate by-member documentation that is focused on
concepts.

Do you agree that this style of documentation would be an improvement over
the current docs?

The ability to achieve such documentation standards is another question. I
am sure it would take a lot of time and effort. I, for one, would really
appreciate such an effort if it were to occur.

Thanks,
Nick