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?