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: Edward Diener (eldiener_at_[hidden])
Date: 2008-10-12 18:55:41

Joaquin M Lopez Munoz wrote:
> Nick Martin <nick <at> transdigita.com> writes:
>> 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.

Naturally good documentation involves both an overall look at how the 
classes/functions of a library work together and the specifics of each 
class/function in the reference part of the documentation.

I see nothing wrong with shortening the reference portion of the 
documentation by referring to concepts, as long as the end-user can go 
from the concept to the generic functionality involved. This may be less 
often the case than you, as a Boost developer, think. In the example you 
give above it may not be obvious to the end-user what functionality a 
random-access iterator guarantees, but there is a good chance such a 
common concept can be found either in the end-user's current 
understanding, in the documentation for the C++ standard library in the 
C++ implementation which the end-user uses, or on the Interenet. For 
other 'concepts', which may be easily recognizable by Boost developers, 
because they deal with them every day, the end-user may be lost in 
determining what generic functionality that concept represents.

So while I agree with you that concept-based explanations in the 
reference portion of a library may often be better than having to 
repeatedly notate what specific functionality is represented by a class, 
especially a template class, I would have you, and Boost developers in 
general, err on the cautious side in supposing that some concept 
terminology is easily understood by the end user.