Re: commit - doxygen comments, new layout - please look


Subject: Re: commit - doxygen comments, new layout - please look
From: Paul Rohr (paul@abisource.com)
Date: Fri Jan 26 2001 - 15:09:30 CST


At 02:46 PM 1/26/01 -0500, Dom Lachowicz wrote:
>I just have a pretty simple (maybe stupid?) question: is it preferable to
>have these comments in the header (.h) files? All existing documentors
>(gtk-doc, for one) generate documentation based on comments in the source
>files.
>
>I just think that docs in the header files serve to clutter them up - you
>want a quick reference of the API if you're looking in there, not a lot of
>confusing comments. If you want to know docs on what exactly a function
>does, you look at the documentation before a function and then at the code
>below it which (hopefully) should do what the comment says...
>
>Just my $0.02

I'll toss my penny in the pot to vote with Dom here. The three times I use
header files are:

  - to get an overview of what that module does
  - as a quick API reference
  - to change them ;-)

This is all the more true now that we've got Doxygen going. If anyone wants
to see comments interspersed with function prototypes, that's where they
should look.

Dom's also got a excellent point that the implementations and docs are more
likely to stay in sync if they're immediately adjacent.

I guess that ups the ante to $0.03 -- think that'll be enough to outbid
Jasper, Thomas, and John?

Paul,
motto -- incorrect documentation can be worse than none at all



This archive was generated by hypermail 2b25 : Fri Jan 26 2001 - 15:02:39 CST