Nick Martin
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