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

Subject: [ggl] Re: Started quickbook doc
From: Mateusz Loskot (mateusz)
Date: 2009-12-01 16:28:16

Barend Gehrels wrote:
> 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.

Yes and no.
If Doxygen comment is 30 or more lines long, it makes definitions
of types divided by these huge blocks, what, in my opinion,
makes harder to read & analyse code with a file - it requires
a lot of scrolling up and down :-)
Comparing time spent on reading comments and time spent
on reading plain source code, the latter is overwhelmingly dominant.

In such case, I prefer to have code pieces more compact and API
reference open in Web browser, so I can look at it from time to time
if I need. But if large comments are scattered in code, I must scroll
constantly, not only from time to time when I need.

Documentation shall be as complete as possible, so it might be bulky.
The problem is that if doc'ed using Doxygen, then all the bulk
lives in between code.
Now, imagine we have header with number of small functions or
metafunctions (like it is common in Spirit code), all belongs to public
interface, so shall be documented, for example this:

http://github.com/mloskot/workshop/blob/master/yatbinrw/yatbinrw.hpp

For every function like:

template <typename T, std::size_t N>
inline T load_big_endian(const void* bytes)
{
    const unsigned char* ptr = static_cast<const unsigned char*>(bytes);
    return unrolled_byte_loops<T, N>::load_big(ptr + N);
}

we have at least 5 lines

/// Brief
/// @param T
/// @param N
/// @param bytes
/// @return

~20 functions x 5 lines put on weight of 100 lines to the initially
compact 250 lines header. This amount of extra stuff in code is
distracting, IMHO.

> 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 checked proto and it confirms my concern I think:
- documentation is not complete, only partially documented public
interfaces, so one still needs to dig the source code to find missing
details
- in headers where it's farily complete, definitions are short it's, but
 docs make source bulky (proto/domain.hpp, 170 lines file with 80 lines
of comments).

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

Sure, I don't say we should not use it, of course. Sharing my experience
and thoughts only.

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