Boost logo

Geometry :

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


Geometry list run by mateusz at loskot.net