Hi Nick, excuse my late answering Nick Martin escribió: [...]
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.
Yes, I understand your point. Let me try to work something out. Would
you think it a
reasonable compromise to add for all those component member functions
*with a description*
a link from the member name at the component synopsis to the associated
description?
For instance, if we have
// ordered indices
template<...>
class name is implementation defined
{
...
iterator begin();
...
std::pair
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.
I don't think the analogy is correct: the standard (or any similar reference documentation) does not deal with the implementation (i.e. engine, breaks and so on) of the components, just with their external interface. The difference with other, more user friendly, documentation (like that in MSDN) lies in the method of exposition, not the information conveyed. One probably does not need to read the standard to be a good C++ programmer, but, in my opinion, the chances that some consult to the standard is eventually needed grow higher as one demands more of the language. [...]
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).
I don't think this documentation is so balanced, as it only mentions the relevant concepts in passing, much as a tutorial would do, without providing exact definitions for them. It entirely relies on by-member annotation. It could be made to have the best of woth worlds if the concepts were described in detail, which it does not seem to do. This documentation is great (and is superbly crafted) for quickly going to a given member function and finding out what it does, but it does nothing to emphasize the recurring themes across components: for instance, map::begin, set::begin, list::begin etc. all are annotated with almost identical descriptions (and even example code!) but nothing suggests that they are all equivalent in the sense that their behavior is dictated by the underlying container concept. Of course any reader will eventually realize this on her own, but I think it's more useful in the long run to stress these commonalities up front.
For instance the STL map class: http://msdn.microsoft.com/en-us/library/s44w4h2s.aspx 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 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.
If you think the proposal I give above is something that would approach your documentation ideal, I can try to find some time to sketch something and show it here at the list (unless we find a volunteer to do it, of course :) ) Joaquín M López Muñoz Telefónica, Investigación y Desarrollo