On Fri, 24 Jun 2005 19:30:03 +0200
Christian Biere wrote:
> > as you've noticed, Doxygen doesn't have @fixme command at now but
> > can FIXME, XXX be considered close to TODO?
>
> XXX is sometimes just a warning or cannot be really fixed but for
> this purpose @todo should be fine.
I see.
> > And I'd like to ask Raphael if possible, do you mind replacing
> > 'NB:' with '@note'?
>
> Personally, I think NOTE is better than NB as the latter requires
> some "insider" knowledge. Maybe scientists (used to) use "nota bene"
> but I didn't know it before and NB is even more "cryptic" than that.
They're still kept as they are, I'll ask him later.
As for STYLE file, I'd like to apply the patch what I attach, but it
may require a little modifying about "[general description of the
file contents]" especially.
I've expected these lines like a headline or summery, actually they
will be shown at file list like I said (you can see at before attached
'files.html'). But I don't know how short they should have to be shown
suitably.
Regards,
--
Daichi
Index: STYLE
===================================================================
RCS file: /cvsroot/gtk-gnutella/gtk-gnutella-current/doc/devguide/STYLE,v
retrieving revision 1.18
diff -u -r1.18 STYLE
--- STYLE 23 Apr 2005 05:40:26 -0000 1.18
+++ STYLE 25 Jun 2005 01:59:36 -0000
@@ -70,20 +70,33 @@
*/
/**
+ * @ingroup [core, lib, gtk etc.]
* @file
*
- * [general desciption of the file contents]
+ * [general description of the file contents]
+ *
+ * ([detailed description of the file contents])
+ *
+ * @author [name of the author (<e-mail address>)]
+ * (@version [number])
+ * @date [year]
*/
The tag $Id is expanded by CVS when the file is committed.
The bracketed sections "[...]" have to be replaced by the respective
- things they describe.
+ things they describe. "(...)" sections are optional, also you can use
+ proper speciall commands (@todo, @note, @warning etc.) in this block
+ (see http://www.stack.nl/~dimitri/doxygen/commands.html for details).
The text in the second comment section starting with "/**" contains the
description of the file as it will show up in the API documentation
generated by Doxygen. It is essential that the "@file" tag is in place
- as shown above.
+ as shown above and please fill [detailed description ...] if possible.
+
+ "@ingroup" is used for grouping at the generated documents, it will be
+ added to the group or groups identified by given groupname (core, lib,
+ etc.). See also doc/api/gtkg-apidoc.main, a groupname is defined here.
2.2 All functions must be consistently commented as:
@@ -111,6 +124,44 @@
is important to make it standout by moving it at the very beginning
of the line, as shown in the example above.
+2.2.1 A short comments at the same line can be commented as follows:
+
+ ex. 1
+
+ #define MACRO_NAME1 blah /**< blah blah */
+ #define MACRO_NAME2 blah /**< blah blah */
+
+ ex. 2
+
+ struct name {
+ struct type *name; /**< blah blah */
+ type *name; /**< blah blah */
+ type name; /**< blah blah */
+ };
+
+ Due to the Doxygen's parsing method, if you forget to add "<" at the
+ comment block (just "/**" there), from the above example, comment for
+ the MACRO_NAME1 will be used for the MACRO_NAME2 or "type *name" will
+ be commented by the comment for "struct type *name". Thus, you can
+ assume the above examples are equivalent to:
+
+ ex. 1
+
+ /** blah blah */
+ #define MACRO_NAME1 blah
+ /** blah blah */
+ #define MACRO_NAME2 blah
+
+ ex. 2
+
+ struct alive {
+ /** blah blah */
+ struct type *name;
+ /** blah blah */
+ type *name;
+ /** blah blah */
+ type name;
+
2.3 Block comments must be formatted as:
/*
@@ -216,7 +267,7 @@
difference between the first non-matching characters. The first
form is much more readable. In contrast to the first, the latter
form reads as: "if NOT strcmp [...]", i.e. "if this is not a
- string comparision [...]", which is clearly wrong.
+ string comparison [...]", which is clearly wrong.
4.3 In general, explicitly tested returned values should appear first
in the condition. This is an extension of rule 4.2:
