Each symbol (function, macro, struct, enum, signal and property) is documented in a separate block. The block is best placed close to the definition of the symbols so that it is easy to keep them in sync. Thus function are usually documented in the c-source and macros, struct and enum in the header file.
/**
* 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.
*/
Paragraph describing the returned result.
Paragraph denoting that this function should no be used anymore. The description should point the reader to the new API.
Description since which version of the code the API is available.
Gtk-doc assumes all symbols (macros, functions) starting with '_' are private. They are treated like static functions.
(FIXME) (stability) (glib-enums, ...)
/** * SomeWidget:some-property: * * Here you can document a property. */ g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);
/**
* FooWidget::foobarized:
* @widget: the widget that received the signal
* @foo: some foo
* @bar: some bar
*
* The ::foobarized signal is emitted each time someone tries to foobarize @widget.
*/
foo_signals[FOOBARIZE] =
g_signal_new ("foobarize",
...
/**
* FooWidget:
* @bar: some #gboolean
*
* This is the best widget, ever.
*/
typedef struct _FooWidget {
GtkWidget parent;
/*< public >*/
gboolean bar;
} FooWidget;