I suggest we use the following to documenting API entry points in
the GNOME libraries.  A sample Perl script written by Michael Zucchi
is included in this package to pull this information and generate a
HTML, man and Docbook output (see gnome-libs/tools/gnome-doc).

   The gtk-doc system (which is what the GNOME project is using to
document its API and the user manuals) has support for these comments
and can generate DocBook output by using this setup.

   The gnome-libs/tools/gnome-doc directory contains a sample Emacs
lisp function that you can load to simplify entering these special
comment.  This utility tool is bound to the "C-x 4 h" key sequence.

Format:

/**
 * function_name:
 * @par1:  description of parameter 1
 * @par2:  description of parameter 2
 *
 * function description.  You can include references to parameters
 * here like @par1 and their font will be set properly on the output.
 * constants can be references with %constant as well to make their
 * string descriptions use a font specification.  This function
 * is simliar to #function_name2 in this and that
 * 
 * return values: an integer.
 */
int
function_name (int par1, char * par2)
{
}

The important parts are:

The first line of an API entry point documentation starts with /**
like the Java documentation system (slash and two stars).  The comment
is formatted with stars at the beginning of each line.  The second
line is the function name, it might include an optional ':' for beautification
purposes. 

A number of keywords can be included in the function_name line, so far
only the [constructor] string has a special meaning (it is used to
list before any other API entry points in the generated output).  We
can define more of those attributes in the future.

Any line from that point on that matches the regular expression:

	^ \* @[a-zA-Z0-9]:

(for example: " * @par1: parameter one")

Is taken to be the declaration of a function parameter.  We can
extract the type of this parameter from the actual function definition. 

After the parameters we have the function description.  If any line of
the function description matches the regexp:

	^ \* [Rr]eturn

It is taken to be the description of the return value for the
function.  

Text inside the descritpion can have any of the following special tags
on the beginning:

   @name:   reference to a parameter.
   %name:   reference to a constant.
   name():   function reference.

Miguel de Icaza (miguel@gnu.org)