Documenting symbols

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 functions are usually documented in the c-source and macros, structs and enums in the header file.

3.3.1. General tags

You can add versioning information to all documentation elements to tell when an API was introduced, or when it was deprecated.

Versioning Tags
Since:

Description since which version of the code the API is available.

Deprecated:

Paragraph denoting that this function should no be used anymore. The description should point the reader to the new API.

(FIXME : Stability information)

Example 3-5General tags
/**
 * foo_get_bar:
 * @foo: some foo
 *
 * Retrieves @foo's bar.
 *
 * Returns: @foo's bar
 *
 * Since: 2.6
 * Deprecated: 2.12: Use foo_baz_get_bar() instead.
 */
Bar *
foo_get_bar(Foo *foo)
{
...

3.3.2. Annotations

Documentation blocks can contain annotation-tags. These tags will be rendered with tooltips describing their meaning. The tags are used by gobject-introspection to generate language bindings. A detailed list of the supported tags can be found on the wiki.

Example 3-6Annotations
/**
 * foo_get_bar: (annotation)
 * @foo: (annotation): some foo
 *
 * Retrieves @foo's bar.
 *
 * Returns: (annotation): @foo's bar
 */
...
/**
 * foo_set_bar_using_the_frobnicator: (annotation) (another annotation)
 *                                    (and another annotation)
 * @foo: (annotation) (another annotation): some foo
 *
 * Sets bar on @foo.
 */

3.3.3. Function comment block

Please remember to:

  • Document whether returned objects, lists, strings, etc, should be freed/unrefed/released.
  • Document whether parameters can be NULL, and what happens if they are.
  • Mention interesting pre-conditions and post-conditions where appropriate.

Gtk-doc assumes all symbols (macros, functions) starting with '_' are private. They are treated like static functions.

Example 3-7Function comment block
/**
 * function_name:
 * @par1:  description of parameter 1. These can extend over more than
 * one line.
 * @par2:  description of parameter 2
 * @...: a %NULL-terminated list of bars
 *
 * 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.
 *
 * Since: 2.2
 * Deprecated: 2.18: Use other_function() instead.
 */
Function tags
Returns:

Paragraph describing the returned result.

@...:

In case the function has variadic arguments, you should use this tag (@Varargs: does also work for historic reasons).

3.3.4. Property comment block

Example 3-8Property comment block
/**
 * SomeWidget:some-property:
 *
 * Here you can document a property.
 */
g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);

3.3.5. Signal comment block

Please remember to:

  • Document when the signal is emitted and whether it is emitted before or after other signals.
  • Document what an application might do in the signal handler.

Example 3-9Signal comment block
/**
 * 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",
                ...

3.3.6. Struct comment block

Example 3-10Struct comment block
/**
 * FooWidget:
 * @bar: some #gboolean
 *
 * This is the best widget, ever.
 */
typedef struct _FooWidget {
  /*< private >*/
  GtkWidget parent;

  /*< public >*/
  gboolean bar;
} FooWidget;

Use /*< private >*/ before the private struct fields you want to hide. Use /*< public >*/ for the reverse behaviour.

Struct comment blocks can also be used for GObjects and GObjectClasses. It is usually a good idea to add a comment block for a class, if it has vmethods (as this is how they can be documented). For the GObject itself one can use the related section docs, having a separate block for the instance struct would be useful if the instance has public fields. One disadvantage here is that this creates two index entries of the same name (the structure and the section).

3.3.7. Enum comment block

Example 3-11Enum comment block
/**
 * Something:
 * @SOMETHING_FOO: something foo
 * @SOMETHING_BAR: something bar
 *
 * Enum values used for the thing, to specify the thing.
 */
typedef enum {
  SOMETHING_FOO,
  SOMETHING_BAR,
  /*< private >*/
  SOMETHING_COUNT
} Something;

Use /*< private >*/ before the private enum values you want to hide. Use /*< public >*/ for the reverse behaviour.