Geometry Boost List: [ggl] Re: Started quickbook doc

Subject: [ggl] Re: Started quickbook doc
From: Mateusz Loskot (mateusz)
Date: 2009-11-30 15:36:06

Hartmut Kaiser wrote:
>> Barend Gehrels wrote:
>>>> Perhaps we could (re)move the Doxygen docs and then the quickbook
>>>> would be moved one level up to ggl/doc.
>>> We probably should look at Doxygen integration too. I saw yesterday a
>>> message from Steven Watanabe about Boost.Random. I would like to see
>>> what the possibilites are, then we can decide what to choose.
>> As I see, Boostbook, thus Quickbook, does provide some Doxygen support:
>>
>> http://www.boost.org/doc/libs/1_41_0/doc/html/boostbook/getting/started
>> .html#boostbook.setup.doxygen
>>
>> However, I'd like to work out solution that does not require
>> us to maintain documentation in two places :-)
> 
> The doxygen integration is meant to generate the API docs with doxygen while
> doing all the rest manually with quickbook. I don't really like this
> approach, but for some people it seems to work fine (see the docs for proto
> or accumulators for instance). 

Hartmut, thank you for clarification.

Given that, in spite of the fact I like Doxygen, I would
stick to Quickbook only. There is number of reasons, in general,
Quickbook and manually crafted documentation is of higher quality
for users, what's been proven/suggested during the review.
Also, I large amount of Doxygen content injected in header files,
especially highly templetized, as disturbing a bit.

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org