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

Subject: [ggl] Re: Started quickbook doc
From: Barend Gehrels (Barend.Gehrels)
Date: 2009-12-01 04:14:01

Mateusz Loskot wrote:
> Hartmut Kaiser wrote:
>   
>>> Barend Gehrels wrote:
>>>       
>>>> 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). 
>>     
>
>
> 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.
>   
I suggested to look at integration and then decide. The good thing of 
Doxygen is that it documents a function, with its arguments, at the 
place where the function is defined. So you can also consider that as 
one place, and consider all in quickbook as scattered.

If I look at proto or random, it does not really look like it is created 
with Doxygen (but it is). So, for a reference, Doxygen might certainly 
make sense.
e.g. 
http://www.boost.org/doc/libs/1_41_0/doc/html/boost/proto/result_of/child_c.html

I don't say that we should use it, but we should consider it. All 
Doxygen tags are still there, it is not a large investment to look at it 
(on the contrary, if we decide to discard it without even looking at it, 
it would be a waste of investment).

Then there are also code samples, but this seems to be possible using 
quickbook alone:
http://www.boost.org/doc/libs/1_41_0/doc/html/quickbook/syntax.html#quickbook.syntax.block.import

Barend

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.osgeo.org/pipermail/ggl/attachments/20091201/2da3da6f/attachment.html