If I made a patch that used doxygen style comments plus a Doxyfile,
would it have a chance of getting accepted? The current comments
aren't useful if you want to generate documentation.
Additionally, the way the functions are laid out, it's harder to grep
for functions. You have to use ctags or something like that because
not every function has a header.
Take for instance this example from code/client/cl_main.c
/*
===============
CL_VoipParseTargets
sets clc.voipTargets according to cl_voipSendTarget
Generally we don't want who's listening to change during a transmission,
so this is only called when the key is first pressed
===============
*/
void CL_VoipParseTargets(void)
Instead of that, you could have this
/** <Brief summary here>
<Description here>
<See also etc>
*/
void
CL_VoipParseTargets(void)
Now I can use doxygen to generate documentation (it knows the Java
style /** */ ... or you can use Qt or whatever) and it's also easier
to search for functions without ctags. I can do this: grep
"^CL_VoipParseTargets(". While I can do 'grep ^CL_VoipParseTargets'
now due to that comment, the comments are inconsistent and ultimately
unnecessary. There are instances where the comment name after
=========== is either wrong (copy/paste) or a typo.
_______________________________________________
ioquake3 mailing list
ioquake3@lists.ioquake.org
http://lists.ioquake.org/listinfo.cgi/ioquake3-ioquake.org
By sending this message I agree to love ioquake3 and libsdl.
