Subject: Re: [boost] Improving Documentation
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2013-10-11 06:12:10
On 11 October 2013 11:02, Mathias Gaunard <mathias.gaunard_at_[hidden]> wrote:
> On 11/10/13 00:13, Niall Douglas wrote:
>> On 10 Oct 2013 at 14:58, Robert Ramey wrote:
>>>> Documentation like this is generated by preprocessing Doxygen XML
>>>> output to integrate it into Boostbook and have a good look for C++
>>>> It has most of what you can expect from Doxygen + the Boostbook stuff
>>>> which gives better cross-referencing than simple Doxygen.
>>> Hmm - I looked at DOxygen and found it lacking for what I wanted. I'm
>>> also disappointed in the Doxygen generated documentation in boost which
>>> to me mostly parrots the source code. On the other hand, I think the
>>> approach (literate programming) has promise but it seemed to me that
>>> one would have to add a lot to Doxygen to generate what I would like
>>> to see. Maybe the "missing magic" is already in on our web site
>>> Basically I don't see where we can coordinate Boostbook with Doxygen.
>>> Perhaps you could include the link which explains this.
>> Boost.Geometry contains a utility called doxygen_xml2qbk which
>> converts Doxygen XML into Quickbook.
> Boostbook comes bundled with an XSLT stylesheet to convert Doxygen XML to
Yes, it does, but apparently it does not produce the quality
Boost.Asio aimed for.
The reference.xsl sheet produces clear index:
and neatly gathers overloads and specialisations in clickable way
leading to documentation of particular version of an entity:
The typical Boost way is to drop in everything into single Synopsis section,
For Boost.Geometry, we wanted to achieve Boost.Asio's effect.
-- Mateusz Loskot, http://mateusz.loskot.net
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk