On Jan 8, 2012, at 12:36 PM, Krzysztof Kosiński wrote:
2012/1/6 Jon Cruz <jon@...18...>:
> The point is the use of "@file" is required by Doxygen, but only for
globals and file statics. If we do not use such items, then we don't have a
requirement to use "@file" in the file.
Please read the documentation snippet I cited again. If you do not
document the file, even with an empty comment, Doxygen will not
extract anything out of it, unless you use the option EXTRACT_ALL. We
currently use this option, but we shouldn't.
Please actually check what you get from that.
The documentation does not say *nothing* will be extracted, only that no globals nor
statics will be extracted.
I created a brand new project with EXTRACT_ALL = NO, and then ran tests. I had files that
were basically identical except for a simple naming variation and that one set had @file
and one set did not.
The set of files that did not have @file, with EXTRACT_ALL set to NO, did in fact get all
items documented that the other set did, except for the types (statics and globals) that
we don't want to be using anyway.
Again, please actually test what you think will happen. Actual behavior of a system always
trumps assumptions drawn merely from reading docs.
Also... key concepts:
* globals (variables, functions etc): Things that don't live in any namespace, mainly
come from legacy C code, get in the way of multithreaded support, etc.
* statics (variables, functions, etc.) that are not class members: The 'static'
keyword was used in C to keep symbols, etc., hidden within a single compilation unit (aka
file). C++ has replaced that with either explicit or anonymous namespaces.
You seem to be getting that EXTRACT_ALL is needed to catch *any* item in a source file.
That is not the case. EXTRACT_ALL only is required to get statics and globals.
Also, class-focus does not mean that files should be undocumented.
There will be files regardless of your focus. A file is not a global
No, not at all. However... if you look through much of our code it consists of just a
class. Doxygen docs do better when one looks at things from that viewpoint, not "hey,
I happened to dump a lot of junk into this one container just because it happened to be
So a bad file comment would be "implements the Foo class". Already covered by
the .h file having just the Foo class and its corresponding documentation on the class.
A good file comment would be "Collection of widget placement routines that have not
yet been migrated to classes or a namespace."
Note that I'm specifically focusing on our more legacy files that come from when this
codebase was pure C and focused on GTK 1.x.