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<iterator,bool> insert(const value_type& x);
 ...
}

then begin would have no link (as there is no explicit description for this
concept-covered memfun) but insert would be linked to the associated description
down within the modifiers section. Would that suit you (to some extent at least)?
I can do this without distrubing the general design of the reference.

   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
_______________________________________________
Boost-users mailing list
Boost-users@lists.boost.org
http://lists.boost.org/mailman/listinfo.cgi/boost-users