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.
Regards, Krzysztof