Subject: Re: [boost] Improving Documentation
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2013-10-10 18:26:28
On 10 October 2013 23:13, Niall Douglas <s_sourceforge_at_[hidden]> 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++
>> > references.
>> > 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 somewhere.
>> 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.
Initially, for Boost.Geometry I ported Boost.Asio XSLT sheet to
generate API reference. The work proved the XSLT application
is scary and highly prone to the bus factor :-)
So, Barend decided to write a custom utility in C++ that is
much easier to reason about, hence maintain.
But still, managing docs is PITA, IMHO.
-- 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