On Nov 7, 2008, at 3:36 PM, Krzysztof Kosiński wrote:
Important points:
- @file on the first line - it has to be present to document a
file, and no point in moving it to the second line since it's boilerplate. When @file isn't present, usually the Inkscape namespace is documented instead of the file.
Standard JavaDoc convention is to have the "/**" start on a line all by itself since it is the start of the comment block. The first operator of the comment is "@file", so that's two separate items forced to a single line.
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.
A second factor is that one might not always need a @file comment. For legacy C code that is more useful, but for C++ code the focus should be on classes. If so, then there is not a need for a @file comment block, since just commenting the class will be sufficient. Also then one can do that with only a "/**" and nothing else.
- Copyright information not included in the doxygen comment - it's
not very useful there
Quite useful split. So the file has *two* comments. The first is a magic documentation comment, and the second is the local copyright information, which doesn't really "document" or explain the use of the file.
- Completely nothing after vim modeline - otherwise it doesn't
work, at least in gedit
You mean nothing other than a final newline character, right?
Microsoft tools have a bad habit of leaving off the final line terminator in text files, but compilers, diff programs, etc, have problems due to that.