Re: [boost] Doxygen XMl docs and BoostBook. (was: [asio] Formal Review)

From: Rene Rivera (grafik.list_at_[hidden])
Date: 2005-12-12 21:42:25

Christopher Kohlhoff wrote:
> --- Caleb Epstein <caleb.epstein_at_[hidden]> 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