Hi, I'm just ready to apply my Doxygen related patch, I've confirmed there's no error at documents generating, both of GTK+ compilation. However it's a little Tsunami class modification (net 723K, covers whole codes now), so I'm bit nervous and would like to hear concerned author's comments about my commenting modification if you're on the list.
Note that, at almost of all, I'm following the attached style guidance (commenting_style.txt) from doc/devguide/STYLE, but some files are heavily modified at the initial comment box, especially Michael's ones what I've attached as an example (src/ui/gtk/gtk1/search_stats.c), if you feel your comments may be messed up by the modification, let me know. Of course, it brings certain benefits e.g. it can be easily understood role of each files (files.html), related functions, macro values (but for me at now...) and check one-stop TODO list through a browser. Regards, -- Daichi
2. COMMENTS ************************************************************
2.1 Every file must start with a comment block like this:
/*
* $Id: STYLE,v 1.18 2005/04/23 05:40:26 cbiere Exp $
*
* Copyright (c) [year], [name of the author]
*
*----------------------------------------------------------------------
* This file is part of gtk-gnutella.
*
* gtk-gnutella is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* gtk-gnutella is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with gtk-gnutella; if not, write to the Free Software
* Foundation, Inc.:
* 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*----------------------------------------------------------------------
*/
/**
* @ingroup [core, lib, gtk etc.]
* @file
*
* [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. "(...)" 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 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:
/**
* Purpose in life.
*
* @param param1 blah blah
* @param param2 blah blah
*
* @returns blah blah.
*/
static struct type *
function_name(...args...)
When the API documentation is generated with Doxygen, the first
sentence (up to the first ".") is treated as the short description
of the function. The complete comment makes up the detailed
description. It is welcome if additional tags like @param or
@returns are used to further enhance the documentation. These
tags are documented in the manual of the Doxygen software package
(see http://www.doxygen.org). The format is largely compatible to Javadoc.
Do not try to use HTML.
Since the function name does not appear in the leading comment, it
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;
search_stats.c.gz
Description: GNU Zip compressed data
files.html.gz
Description: GNU Zip compressed data
