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.