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

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

Hi Mateusz,

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

OK, I agree with that. It is a new argument, but it makes certainly sense.

> [snipped examples]
> ~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.
>   

I agree. It is too much. Within Boost.Geometry the proportions are 
different, but I agree that it can grow if you want to describe it 
carefully.

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

So let's defer it and first look how the (start of the) QuickBook 
documentation will look like, including reference section with function 
documentation. So that will probably be the way to take. If 
satisfactory, we can remove the doxygen stuff from the code.

Regards, Barend

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.osgeo.org/pipermail/ggl/attachments/20091202/14fec0d5/attachment.html