On Jan 2, 2012, at 8:44 AM, Krzysztof KosiĆski wrote:
2012/1/1 Kris De Gussem <kris.degussem@...400...>:
Hi all
I like to go on with the replacement of the deprecated wrapper functions in src/xml/repr.h with direct calls to their respective functions (as listed in the first section on http://wiki.inkscape.org/wiki/index.php/Janitorial_tasks). Any objections?
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.
Again, for C++ we should be avoiding globals, so the need to document such should be very restricted. If items are only in a .cpp file and not in any .h file, then they really should not be part of the public parts, etc.
So, yes, the doxygen information on @file is accurate in the area that it is speaking to, but that area is one that we are actively avoiding, so becomes much less of an issue.