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.ht...) 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?
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
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 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