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 variable.
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 there"
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.