Another problem is that the wiki appears to be broken. When I try to edit a page, all I get is a bunch of PHP errors:

Warning: file(/var/www/wiki.inkscape.org/htdocs/extensions/SpamBlacklist/wikimedia_blacklist) [function.file]: failed to open stream: No such file or directory in /var/www/wiki.inkscape.org/htdocs/extensions/SpamBlacklist/SpamBlacklist_body.php on line 97

Warning: array_merge() [function.array-merge]: Argument #2 is not an array in /var/www/wiki.inkscape.org/htdocs/extensions/SpamBlacklist/SpamBlacklist_body.php on line 97

Warning: array_map() [function.array-map]: Argument #2 should be an array in /var/www/wiki.inkscape.org/htdocs/extensions/SpamBlacklist/SpamBlacklist_body.php on line 102

Warning: array_filter() [function.array-filter]: The first argument should be an array in /var/www/wiki.inkscape.org/htdocs/extensions/SpamBlacklist/SpamBlacklist_body.php on line 102

Warning: require(/var/www/wiki.inkscape.org/htdocs/extensions/CheckUser//CheckUser.hooks.php) [function.require]: failed to open stream: No such file or directory in /var/www/wiki.inkscape.org/htdocs/includes/AutoLoader.php on line 918

Fatal error: require() [function.require]: Failed opening required '/var/www/wiki.inkscape.org/htdocs/extensions/CheckUser//CheckUser.hooks.php' (include_path='.:/var/www/wiki.inkscape.org/htdocs:/var/www/wiki.inkscape.org/htdocs/includes:/var/www/wiki.inkscape.org/htdocs/languages') in /var/www/wiki.inkscape.org/htdocs/includes/AutoLoader.php on line 918

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.

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)

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.