Somebody undid my changes to the files in src/bind/, so I'd like to discuss the doxygen convention used for files here. I already said about this in another thread but it wasn't too visible. I think the proper template for a source file goes like this:
/** @file * @brief Brief description of what this file contains */ /* Authors: * Some Author <author@...2068...> * * Copyright (C) 2008 Authors * Released under GNU GPL, read the file 'COPYING' for more information */
#ifndef INCLUDE_GUARD #define INCLUDE_GUARD
// ... code ...
#endif
/* Local Variables: mode:c++ c-file-style:"stroustrup" c-file-offsets:((innamespace . 0)(inline-open . 0)(case-label . +)) indent-tabs-mode:nil fill-column:99 End: */ // vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:encoding=utf-8:textwidth=99 :
Important points: 1. @file on the first line - it has to be present to document a file, and no point in moving it to the second line since it's boilerplate. When @file isn't present, usually the Inkscape namespace is documented instead of the file. 2. Copyright information not included in the doxygen comment - it's not very useful there 3. Include guard after file description and copyright information - this is the current convention; it makes the placement consistent between headers and .cpp files 4. Completely nothing after vim modeline - otherwise it doesn't work, at least in gedit
It seems the main issue of contention was 2, but I don't know what are the arguments for leaving the copyright info in the documentation. I don't think there are any copyright issues with the doxygen comments because the documentation is meant for internal use and not widely useful outside of the Inkscape developer community. Even if that's the case we could put a (C) notice on the main page so that other pages are not cluttered with duplicated information.
Regards, Krzysztof Kosiński