On Jan 2, 2012, at 3:01 PM, Krzysztof Kosiński wrote:
2012/1/2 Jon Cruz <jon@...18...>:
It should be OK.
I note that the wiki page has misleading information on @file Doxygen comments. If a file is not documented, then by default none of its contents are processed. We override this by using EXTRACT_ALL in our default Doxyfile, but in the future we should rely less on this option.
"Let's repeat that, because it is often overlooked: to document global objects (functions, typedefs, enum, macros, etc), you must document the file in which they are defined." http://www.stack.nl/~dimitri/doxygen/docblocks.html
Once we get back to the wiki I'll see what I can do here.
In general we do want to avoid the need for @file, especially because we should be avoiding globals, etc.
What? A file is not a global variable. There is no way to avoid using files and there is no reason we should, so it makes sense to write a note on what each file contains.
No,
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.
In the big picture of things, the old C way of organizing was by file, and having @file would be required in that approach. However the newer approach is to focus on classes, namespaces, etc., and in this view of things commenting on the contents of a specific file is not really that helpful.
For example, the main contents of most .cpp files should be a class, and a class should all be in a single .cpp file. If we have foo.cpp, then we would expect it to contain a class called Foo. In that case then one would expect a @file comment in foo.cpp to be
/** * @file * this file contains the implementation of the Foo class. */
However we already documented the Foo class itself at its declaration (not definition). And Doxygen will automatically tell one the file or files that a class is both declared and defined in, without any @file tags present.
Again, to stress the main point: we should be moving away from any static and globals and replace them with proper namespace and/or class use. Functions in a .cpp file that were defined 'static' in the C world should instead be placed in anonymous namespaces in the newer C++ paradigm. And the use of the @file tag is only required by doxygen in the cases that we want to avoid in modern C++ code. (but, yes, it is appropriate for our legacy code that has not yet been cleaned up).
(and, yes, I did test all of this in simple stand-alone projects just to be sure of current behavior)