Doxygen conventions
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
On Nov 7, 2008, at 3:36 PM, Krzysztof Kosiński wrote:
Important points:
- @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.
Standard JavaDoc convention is to have the "/**" start on a line all by itself since it is the start of the comment block. The first operator of the comment is "@file", so that's two separate items forced to a single line.
So a rationale for having it on separate lines is that we don't have a single 'object' that is "/**...@...2069...", but rather two separate objects, one "/**" that is "start of magic comment block" and one that is "@file" and is "here is the magic comment to apply to the whole file.
A second factor is that one might not always need a @file comment. For legacy C code that is more useful, but for C++ code the focus should be on classes. If so, then there is not a need for a @file comment block, since just commenting the class will be sufficient. Also then one can do that with only a "/**" and nothing else.
- Copyright information not included in the doxygen comment - it's
not very useful there
Quite useful split. So the file has *two* comments. The first is a magic documentation comment, and the second is the local copyright information, which doesn't really "document" or explain the use of the file.
- Completely nothing after vim modeline - otherwise it doesn't
work, at least in gedit
You mean nothing other than a final newline character, right?
Microsoft tools have a bad habit of leaving off the final line terminator in text files, but compilers, diff programs, etc, have problems due to that.
On Fri, Nov 07, 2008 at 04:10:44PM -0800, Jon A. Cruz wrote:
So a rationale for having it on separate lines is that we don't have a single 'object' that is "/**...@...2069...", but rather two separate objects, one "/**" that is "start of magic comment block" and one that is "@file" and is "here is the magic comment to apply to the whole file.
I'm not convinced of the importance (I'm not sure I understand what JonCruz means by `object'), but have no strong opinion on the question.
A second factor is that one might not always need a @file comment.
Files need to have a @file comment for any of the doxygen comments in that file to have effect, I believe.
I've just tried the following:
(cd src && doxygen) mv -i doxygen{,-without} <add @file comment to src/sp-rect.cpp> (cd src && doxygen) diff -dur -I 'Generated on Sat' doxygen* rgrep -l 'unrounded corners of the rectangle' doxygen-without/html [No matches.] rgrep -l 'unrounded corners of the rectangle' doxygen/html [doxygen/html/sp-rect_8cpp.html]
The doxygen-without/html directory has no sp-rect_8cpp.html that contains all the doxygen comments of src/sp-rect.cpp.
- Copyright information not included in the doxygen comment - it's
not very useful there
I concur. I wouldn't object to having authors/copyright in doxygen form if appropriate markup were used and if someone were to give a reason for it being in the Doxygen output, but I believe that the minor ugliness of a split comment is better than having all the author stuff mixed with the file description comment.
- Completely nothing after vim modeline - otherwise it doesn't work,
at least in gedit
You mean nothing other than a final newline character, right?
I'm sure he did consider the terminating newline character to be part of the line, but yes, good to clarify.
More generally, every line in C/C++ source files (and probably text files generally) should be terminated by a newline.
pjrm.
If your "doxyfile" config file specifies smartly enough which files should be covered and which aren't, @file is not necessary at all.
I've used doxygen on Java, C++, and C files on several projects, and have never needed @file.
If all you want to document is API's then the .h files are enough. Doing the .cpp files is useful for the hyperlinked, cross-referenced html copy of the source.
bob
On 11/7/2008 9:36 PM, Peter Moulder wrote:
On Fri, Nov 07, 2008 at 04:10:44PM -0800, Jon A. Cruz wrote:
So a rationale for having it on separate lines is that we don't have a single 'object' that is "/**...@...2069...", but rather two separate objects, one "/**" that is "start of magic comment block" and one that is "@file" and is "here is the magic comment to apply to the whole file.
I'm not convinced of the importance (I'm not sure I understand what JonCruz means by `object'), but have no strong opinion on the question.
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
On Nov 8, 2008, at 5:25 AM, Krzysztof Kosiński wrote:
- @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.
But here is one main point. With C code we would end up with files of only functions. However, with C++ we really should have most functions as part of some class.
So I agree about consistency, but posit that it is better to simplify to fewer comments and fewer ties to artificial physical groupings (files) and instead focus on logical construct groupings (namespaces and classes).
- 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.
Actually it's not just for the documentation software system.
It is also for the programmers working on the files. The standard came from JavaDoc, and has "/**" on a line by itself as the base. Any programmers who work with Java, or with doc++ or with many other C/C+ + documentation systems are used to that. It makes things "click" or register visibly.
Doxygen has it's own system (including @file), but can use the standard approach. And in this instance what I mean by "standard" is the convention started by the widely prevalent system that pushed such docs into common use and that is supported by all the auto documentation tools I've evaluated.
A little offtopic.
I deleted the old src/Doxyfile and created a new one in trunk's root. Added many settings; now it also generates an include dependency graph, very nifty :-) (I use doxygen on Inkscape for this sole purpose of seeing why some files get recompiled for a change in a seemingly unrelated header file)
(windows users: install graphviz and add 'dot.exe' to your path)
Cheers, Johan
Hi Bob,
Could you please compile a new windows build with full debug options? This would help our users and bug-reporters to get backtraces, which are indispensible considering our current instability.
And while you're at it, please make a minor change to http://inkscape.modevia.com/win32/HEADER.html: our bug-reporters should use
(gdb) run c:\temp\your-file-name.svg
Instead of just
(gdb) run
because for some reason it is impossible to open files from within Inkscape when using gdb on Windows.
Thanks,
Diederik
-----Original Message----- From: Bob Jamison [mailto:rwjj@...127...] Sent: 2008 nov 08 6:37 To: Peter Moulder; inkscape Subject: Re: [Inkscape-devel] Doxygen conventions
If your "doxyfile" config file specifies smartly enough which files should be covered and which aren't, @file is not necessary at all.
I've used doxygen on Java, C++, and C files on several projects, and have never needed @file.
If all you want to document is API's then the .h files are enough. Doing the .cpp files is useful for the hyperlinked, cross-referenced html copy of the source.
bob
On 11/7/2008 9:36 PM, Peter Moulder wrote:
On Fri, Nov 07, 2008 at 04:10:44PM -0800, Jon A. Cruz wrote:
So a rationale for having it on separate lines is that we don't have a single 'object' that is "/**...@...2069...", but rather two separate objects, one "/**" that is "start of magic comment block" and one that is
"@file"
and is "here is the magic comment to apply to the whole file.
I'm not convinced of the importance (I'm not sure I understand what
JonCruz
means by `object'), but have no strong opinion on the question.
This SF.Net email is sponsored by the Moblin Your Move Developer's
challenge
Build the coolest Linux based applications with Moblin SDK & win great
prizes
Grand prize is a trip for two to an Open Source event anywhere in the
world
http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Inkscape-devel mailing list Inkscape-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
On 11/10/2008 4:19 AM, Diederik van Lierop wrote:
Hi Bob,
Could you please compile a new windows build with full debug options? This would help our users and bug-reporters to get backtraces, which are indispensible considering our current instability.
Done.
And while you're at it, please make a minor change to http://inkscape.modevia.com/win32/HEADER.html: our bug-reporters should use
(gdb) run c:\temp\your-file-name.svg
Instead of just
(gdb) run
because for some reason it is impossible to open files from within Inkscape when using gdb on Windows.
That has not happened to me. Usually when gdb freezes, it is because of a new thread launching, and hitting <enter> continues it.
participants (6)
-
unknown＠example.com -
Bob Jamison -
Diederik van Lierop -
Jon A. Cruz -
Krzysztof Kosiński -
Peter Moulder