On Nov 7, 2008, at 3:36 PM, Krzysztof Kosiński wrote:

Important points:

1. @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.

2. 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.

4. Completely nothing after vim modeline - otherwise it doesn't work, at

least in gedit