These are the comment blocks used in Gnome source files to document
functions (and macros if you want).

/**
 * function_name:
 * @par1:  description of parameter 1. These can extend over more than
 * one line.
 * @par2:  description of parameter 2
 *
 * The function description goes here. You can use @par1 to refer to parameters
 * so that they are highlighted in the output. You can also use %constant
 * for constants, function_name2() for functions and #GtkWidget for links to
 * other declarations (which may be documented elsewhere).
 * 
 * Returns: an integer.
 */

The block starts with '/**'.
Each line starts with ' * '.

The second line is the function name, optionally followed by a ':'.

Following the function name are the parameters, e.g. '@par1:' above.

A blank line MUST be used to separate parameter descriptions from the main
description (otherwise it is assumed to be a continuation of the parameter
description.)

After the main description is a 'Returns:' line to describe the
returned value of the function (if it is not void).

Text inside the descriptions can use these special characters (they
will be expanded into appropriate DocBook tags):

   @name   a parameter.
   %name   a constant.
   name()  reference to a function, or a macro which works like a function
	   (this will be turned into a hypertext link if the function is
	   documented anywhere).
   #name   reference to any other type of declaration, e.g. a struct, enum,
	   union, or macro (this will also be turned into a link if possible).

To avoid problems, the characters '<', '>' and '&' in the descriptions are
converted into the SGML entities &lt; &gt; and &amp;.
This means that you can't use DocBook SGML tags.