[patch] libhal documentation

[John (J5) Palmieri]

On Tue, 2005-05-10 at 19:35, Rohan McGovern wrote:
> On Wed, 11 May 2005 04:15, David Zeuthen wrote:
> > ...
> > I see that you added the Doxygen comments to the libhal.h file and there
> > are some duplicates (e.g. libhal_ctx_shutdown has comments in both
> > libhal.h and libhal.c). I think it would be nice to only have these in
> > one place (I think, traditionally, one uses the C file as far as it's
> > possible). Any chance you can clear this up?
> >
> 
> OK, the .h file now has only brief comments, while the .c file has the full 
> documentation, I hope this is acceptable :-)  I have usually used the .h file 
> for doxygen comments, since sometimes the .h file is all users have, and I 
> still couldn't bring myself to remove the comments from .h entirely, but I 
> think it should be OK now; the brief comments in libhal.h aren't likely to 
> ever need to change, so there's only one copy of documentation to maintain.
> 
> Patch is, once again, available at 
> http://everest.fit.qut.edu.au/~n4722418/hal_cvs_doc.patch.gz :-)

Ya, I never really understood why we do the documentation in the C files
(isn't the header files just documentation of the interfaces anyway?),
but the convention is to have the header files as sparse as possible and
put all verbosity in the c files.

--
J5

_______________________________________________
hal mailing list
hal at lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/hal