Subject: Re: commit - doxygen comments, new layout - please look
From: Dom Lachowicz (cinamod@hotmail.com)
Date: Fri Jan 26 2001 - 17:25:55 CST
Sam TH wrote:
>Well, that's where I would want the comments too - as part of the API
>reference. Maybe we are thinking of different kinds of comments. I
>have been thinking of these as comments that users of the function
>would want. Are other people thinking of them as comments about the
>implementation of the functions?
No. You *never* want documentation like JavaDoc or DoxyGen to tell *how* a
certain bit of code is implemented. You want your code to be
self-documenting and possibly have // comments inside of the function if
anything is hazy or needs explanation. You want your JavaDoc/DoxyGen stuff
to say "FV_View->appendFmt() takes these xxx arguments and makes your text
look funny depending on their values. It presupposes X and Y and returns Z"
The H files should contain as little of documentation as is humanly
possible. // comments before a function should be discouraged. You might
possibly use them before an enum but that's about it... You want H files to
see the API and exactly what this class does/defines, as well as for editing
its methods and variables. To see what the H file represents, well, that's
why we have IE and Mozilla - to view the DoxyGen output online - that's why
it exists. The C/C++ code hopefully has the DoxyGen comments before the
methods. JavaDoc example:
/**
* Function foo prints your string to the screen and returns the length
* Of the string printed
* @param str - the String to print out
* @returns - the length of @str
* @throws NullPointerException if @str is null
* @author Dom Lachowicz Jan 26, 2000 <cinamod@hotmail.com>
*/
int foo (String str) throws NullPointerException
{
if (str == null) throw new NullPointerException ();
System.out.println( str);
return (int) str.length ();
}
Dom
_________________________________________________________________
Get your FREE download of MSN Explorer at http://explorer.msn.com
This archive was generated by hypermail 2b25 : Fri Jan 26 2001 - 17:26:01 CST