Writing API docs

The API documentation for most of the Glib, GObject, GTK+ and GNOME libraries is built with a combination of complex tools. Typically, the part of the documentation which describes the behavior of each function is extracted from the specially-formatted source code comments by a tool named gtk-doc which generates docbook xml and merges this docbook xml with a set of master xml docbook files. These xml docbook files are finally processed with xsltproc (a small program part of the libxslt library) to generate the final html output. Other tools can be used to generate pdf output from the source xml. The following code excerpt shows what these comments look like.

/**
 * gtk_widget_freeze_child_notify:
 * @widget: a #GtkWidget
 * 
 * Stops emission of "child-notify" signals on @widget. The signals are
 * queued until gtk_widget_thaw_child_notify() is called on @widget. 
 *
 * This is the analogue of g_object_freeze_notify() for child properties.
 **/
void
gtk_widget_freeze_child_notify (GtkWidget *widget)
{
...

The great thoroughful documentation on how to setup and use gtk-doc in your project is provided on the gnome developer website.