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)

Exempel 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. 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.

Also, take a look at gobject introspection annotation tags: http://live.gnome.org/GObjectIntrospection/Annotations

Exempel 3-6Function 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.3. Property comment block

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

          

3.3.4. 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.

Exempel 3-8Signal 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.5. Struct comment block

Exempel 3-9Struct 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 usualy a good idea to add a comment blco 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.6. Enum comment block

Exempel 3-10Enum 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.