Re: [boost] Improving Documentation

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++
>>>> 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.
>
>
> Boostbook comes bundled with an XSLT stylesheet to convert Doxygen XML to
> Boostbook.

Yes, it does, but apparently it does not produce the quality
Boost.Asio aimed for.

The reference.xsl sheet produces clear index:

http://www.boost.org/doc/libs/1_54_0/doc/html/boost_asio/reference.html

and neatly gathers overloads and specialisations in clickable way
leading to documentation of particular version of an entity:

http://www.boost.org/doc/libs/1_54_0/doc/html/boost_asio/reference/read.html

The typical Boost way is to drop in everything into single Synopsis section,
like here:

http://www.boost.org/doc/libs/1_54_0/libs/spirit/doc/html/spirit/qi/reference/parse_api/iterator_api.html

For Boost.Geometry, we wanted to achieve Boost.Asio's effect.

Best regards,
-- 
Mateusz  Loskot, http://mateusz.loskot.net