On Fri, Nov 07, 2008 at 04:10:44PM -0800, Jon A. Cruz wrote:
So a rationale for having it on separate lines is that we don't have a single 'object' that is "/**...@...2069...", but rather two separate objects, one "/**" that is "start of magic comment block" and one that is "@file" and is "here is the magic comment to apply to the whole file.
I'm not convinced of the importance (I'm not sure I understand what JonCruz means by `object'), but have no strong opinion on the question.
A second factor is that one might not always need a @file comment.
Files need to have a @file comment for any of the doxygen comments in that file to have effect, I believe.
I've just tried the following:
(cd src && doxygen) mv -i doxygen{,-without} <add @file comment to src/sp-rect.cpp> (cd src && doxygen) diff -dur -I 'Generated on Sat' doxygen* rgrep -l 'unrounded corners of the rectangle' doxygen-without/html [No matches.] rgrep -l 'unrounded corners of the rectangle' doxygen/html [doxygen/html/sp-rect_8cpp.html]
The doxygen-without/html directory has no sp-rect_8cpp.html that contains all the doxygen comments of src/sp-rect.cpp.
- Copyright information not included in the doxygen comment - it's
not very useful there
I concur. I wouldn't object to having authors/copyright in doxygen form if appropriate markup were used and if someone were to give a reason for it being in the Doxygen output, but I believe that the minor ugliness of a split comment is better than having all the author stuff mixed with the file description comment.
- Completely nothing after vim modeline - otherwise it doesn't work,
at least in gedit
You mean nothing other than a final newline character, right?
I'm sure he did consider the terminating newline character to be part of the line, but yes, good to clarify.
More generally, every line in C/C++ source files (and probably text files generally) should be terminated by a newline.
pjrm.