Example of various types of gtk-doc

gtkdoc-example.c

/* Documenting a module (generally a .c file) */

/**
 * SECTION:section-name
 * @title: SectionName
 * @short_description: Frobnicate foo
 * 
 * Description of modules purpose and most likely used functions.
 * 
 * You should put this at the top of your .c file, after the includes.
 */

/* section-name generally maps to file-name without the suffix */

/* Documenting a Function */

/**
 * function_name:
 * @param1: A #FooBar
 * @param2: (out): a location for a gint
 *
 * Function description.
 * 
 * You should put this directly above your function definition in the .c file.
 *
 * Returns: (transfer none): A #GtkWidget.
 * 
 * Since: 3.18.2
 */
GtkWidget *
function_name (FooBar *param1,
               gint   *param2)
{
  /* ... */
}

/* Documenting a property */

/**
 * FooBar:my-property:
 *
 * The #FooBar:my-property is the foo of the bar. You may want to
 * use it to baz the bop.
 * 
 * You should put this above the properties [PROP_FOO] in your .c file
 * (in foo_bar_class_init).
 */

/* Documenting a signal (aka events) */

/**
 * FooBar::signal-name:
 * 
 * The #FooBar::signal-name signal is emitted when the foo frobnicates
 * the bar.
 * 
 * This should be placed directly above the signals [SIGNAL_NAME] line
 * in your .c file. (In foo_bar_class_init).
 * 
 * Since: 3.18
 */