Replying to all issues brought up here:
1. Yes, of course a newline should come after the Vim modeline. It's just that gedit and some other editors don't even show this terminating newline, so that it can't be deleted. I'm mostly using gedit with many plugins so for me it's on the last line :)
2. @file is necessary if EXTRACT_ALL is not specified. Currently it is. However, I think it's good to add @file and the short description even to files defining only a single class, to keep consistency between files with classes and files with functions only.
3. Both "objects" on the first line don't give any useful information to the reader, they are just hints for the documentation system telling what this comment is. If the @file line had any useful information it would merit moving it to a separate line.
4. If the separation of comments looks ugly, it could be modified so that the separation doesn't look too bad, e.g.: /** @file * @brief Short description *//* * Authors: * Some Author <some@...2068...> * * Copyright (C) 2008 Authors * Released under GNU GPL; see the file 'COPYING' for more information */
5. When we agree on something, the coding style page could be updated to include it.
Regards, Krzysztof Kosiński