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
