Subject: Re: commit - doxygen comments, new layout - please look
From: Martin Sevior (msevior@mccubbin.ph.unimelb.edu.au)
Date: Fri Jan 26 2001 - 15:52:31 CST
On Fri, 26 Jan 2001, Paul Rohr wrote:
> 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 absolutely how I use the headers too.
>
> 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?
Well, I have to agree and Dom and Paul here too. I'd rather leave the
headers simple and clean. The name of the method/variable plus a
little // comment is all I'd want.
Martin
This archive was generated by hypermail 2b25 : Fri Jan 26 2001 - 15:52:42 CST