On Nov 8, 2008, at 5:25 AM, Krzysztof Kosiński wrote:

2. @file is necessary if EXTRACT_ALL is not specified. Currently it is.

However, I think it's good to add @file and the short description even to

files defining only a single class, to keep consistency between files with

classes and files with functions only.

But here is one main point. With C code we would end up with files of only functions. However, with C++ we really should have most functions as part of some class.

So I agree about consistency, but posit that it is better to simplify to fewer comments and fewer ties to artificial physical groupings (files) and instead focus on logical construct groupings (namespaces and classes).

3. Both "objects" on the first line don't give any useful information to the

reader, they are just hints for the documentation system telling what this

comment is. If the @file line had any useful information it would merit

moving it to a separate line.

Actually it's not just for the documentation software system.

It is also for the programmers working on the files. The standard came from JavaDoc, and has "/**" on a line by itself as the base. Any programmers who work with Java, or with doc++ or with many other C/C++ documentation systems are used to that. It makes things "click" or register visibly.

Doxygen has it's own system (including @file), but can use the standard approach. And in this instance what I mean by "standard" is the convention started by the widely prevalent system that pushed such docs into common use and that is supported by all the auto documentation tools I've evaluated.