Boost logo

Boost :

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.

Best regards,

Mateusz  Loskot,

Boost list run by bdawes at, gregod at, cpdaniel at, john at