Christopher Kohlhoff wrote:
--- Caleb Epstein <caleb.epstein@gmail.com> wrote: [...]
The Reference documentation for the library is quite good overall, but it might make sense to elide some of the low-level detail in places. I don't think most users will care that stream_socket is simply a typedef of basic_stream_socket<> (though this could be mentioned on the basic_stream_socket<> documentation). The extra clicks required to get at the documentation you actually need (that of basic_stream_socket) can be frustrating.
Some time soon I'm going to look at using doxygen's XML output to generate the output in a friendlier format, and when I do this I'll automatically clone the documentation from basic_stream_socket<> to stream_socket, etc. I do like how doxygen keeps the documentation close to the code, but I find its generated HTML a little quirky.
You really should look at the Doxygen XML output integration into the BoostBook documentation chain. In particular it allows for the integration of non-reference documentation with the reference style docs from Doxygen. For example see the Program Options lib <http://www.boost.org/doc/html/program_options.html> (uses Dox and BoostBook), the String Algo lib <http://www.boost.org/doc/html/string_algo.html> (again Dox+BoostBook), and in CVS HEAD Xpressive which is Dox and Quickbook. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com -- 102708583/icq - grafikrobot/aim - Grafik/jabber.org