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:
>>> .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.

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:


-------------- next part --------------
An HTML attachment was scrubbed...

Geometry list run by mateusz at