Joaquin M Lopez Munoz wrote:
Nick Martin
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.