Introspection gtk-doc annotations

Table of contents:

Annotation syntax

The basic syntax looks like this:

   1  /**
   2   * lib_symbol_name: (annotation1) (annotation2)
   3   * @param_first: (annotation1) (annotation2) (...): documentation for first 
   4   * @param_second: (annotation1) (annotation2) (...): documentation for second
   5   *
   6   * Description of the symbol.
   7   *
   8   * Returns: (annotation1) (annotation2) (...): Returns stuff which you have to free after use
   9   */

Where lib_symbol_name is the function you want annotate.

first is the name of the first parameter and second is the name of the second parameter.

Return value: is a synonym for Returns:

NOTE: The last colon (:) is necessary in parameter/return value annotations; the annotations will not be included without it.

NOTE: No trailing colon after annotations for symbols names (top line of gtk doc comment). If you include a colon then gtk-doc won't recognize the line.

There are more illustrative examples below.

Possible annotations

Methods and Types

In function/type header:




Causes the function/type to be omitted from the introspected output


Per parameter:




out parameter (automatically determine allocation)

(out caller-allocates)

out parameter, where the calling code must allocate storage

(out callee-allocates)

out parameter, where the receiving function must allocate storage


in parameter


in/out parameter


Only valid for parameters. Means that the caller may pass in NULL instead of a pointer to a string/struct/object. For (out) parameters, NULL signifies that the output value is to be ignored.

(default VALUE)

default value for a parameter Not implemented yet: bug

(error-domains DOM1 DOM2)

Typed errors. Similar to throws in Java Not implemented yet


This parameter is a "user_data", for callbacks; many bindings can pass NULL here

(closure PARAM)

This parameter is a callback and the "PARAM" parameter is the data that will be passed on to the callback.

(scope TYPE)

scope type for a parameter. See Scope types section below.

Parameters and Return values

Per parameter or return value:



(transfer MODE)

set transfer for this parameter (see below)

(element-type TYPE)

Specify the type of the element inside a container. Can be used in combination with (array).

(element-type KTYPE VTYPE)

Specify the types of the keys and values in a dictionary-like container (eg, GHashTable).



(array fixed-size=N)

array of fixed length N

(array length=PARAM)

array, fetch the length from parameter PARAM

(array zero-terminated=1)

array which is NULL terminated

(type TYPE)

override the parsed C type with given type


used to indicate that the parameter or return value is only useful in C and should be skipped (bug)

(attribute my.key value)

Used to specify attributes (free-form annotations)

Method's Heading

Additional gtk-doc headings:



Attributes: (my.key1 val1) (my.key2 val2) (...)

Used to specify attributes (free-form annotations).

Deprecated: VERSION

This symbol has been deprecated since version VERSION

Rename to: SYMBOL

Advise to rename the original symbol's name to SYMBOL. If a Rename To yields to a function name that is already used, the original binding for that name is removed.

Value: VALUE

Used to override constants for defined values, VALUE contains the evaluated value

Transfer: VALUE

Transfer ownership for this property, see transfer modes below


Override the default type, used for properties


Stability of the symbol

Virtual: slot_name

This function is the invoker for a virtual method.

Unref func:

Function used to unref a struct, must be a GTypeInstance

Ref func:

Function used to ref a struct, must be a GTypeInstance

Set value func:

Function used to convert from a struct to a GValue, must be a GTypeInstance

Get value func:

Function used to convert a struct from a GValue, must be a GTypeInstance


This function was added in version VERSION

Returns/Return value:

See above

Transfer Modes

Transfer modes:

  • none: the recipient does not own the value

  • container: the recipient owns the container, but not the elements. (Only meaningful for container types.)

  • full: the recipient owns the entire value. For a refcounted type, this means the recipient owns a ref on the value. For a container type, this means the recipient owns both container and elements.

  • floating: alias for none, can be used for floating objects.

container is usually a pointer to a list or hash table, eg GList, GSList, GHashTable etc. elements is what is contained inside the list: integers, strings, GObjects etc.

Callbacks Scope Types

  • The scope annotation is only used for parameters which are callbacks, it indicates the duration of the call. It is mainly used by language bindings wanting to know when the resources required to do the call (for instance ffi closures) can be freed. The three different allowed values are:
    • call (default) - Only valid for the duration of the call. Can be called multiple times during the call.

    • async - Only valid for the duration of the first callback invokation. Can only be called once.

    • notified - valid until the GDestroyNotify argument is called. Can be called multiple times before the GDestroyNotify is called.

    Example of a function using the call scope is g_slist_foreach, async: g_file_read_async and notified g_idle_add_full. A few more scope types are possible, but they are not yet added in lack

    of proper use cases. See bug 556489 for some discussion about this.

Default Annotations

To avoid having the developers annotate everything the introspection framework is providing sane default annotation values for a couple of situations:

  • inout and out parameters: (transfer full)
  • return values (transfer full)
  • "gchar*" means (type utf8) (transfer full)
  • "const gchar*" means (type utf8) (transfer none)
  • "GObject*" defaults to (transfer full)

Default Basic Types

Basic types:

  • gpointer: pointer to anything
  • gboolean:boolean
  • gint[8,16,32,64]: integer
  • guint[8,16,32,64]: unsigned integer
  • glong: long
  • gulong: unsigned long
  • GType: a gtype
  • gfloat: float
  • gdouble: double
  • utf8: string encoded in utf8
  • filename: filename string
  • guint8 array: binary data

Reference to Object Instances


  • Object: a GObject instance
  • Gtk.Button: a Gtk.Button instance

Annotation examples


   1 /**
   2  * mylib_get_constant1:
   3  *
   4  * Return value: (transfer full): a constant, free when you used it
   5  */
   6 gchar *
   7 mylib_get_constant1 (void) 
   8 {
   9    return g_strdup("a constant");
  10 }

   1 /**
   2  * mylib_get_constant2:
   3  *
   4  * Return value: (transfer none): another constant
   5  */
   6 const gchar *
   7 mylib_get_string2 (void) 
   8 {
   9    return "another constant";
  10 }

   1 /**
   2  * mylib_get_string_list1:
   3  *
   4  * Return value: (element-type utf8) (transfer full): list of constants,
   5  *               free the list with g_slist_free and the elements with g_free when done.
   6  */
   7 GSList *
   8 mylib_get_string_list1 (void) 
   9 {
  10    GSList *l = NULL;
  11    l = g_slist_append (l, g_strdup ("foo"));
  12    l = g_slist_append (l, g_strdup ("bar"));
  13    return l;
  14 }

   1 /**
   2  * mylib_get_string_list2:
   3  *
   4  * Return value: (element-type utf8) (transfer container): list of constants
   5  *               free the list with g_slist_free when done. 
   6  */
   7 GSList *
   8 mylib_get_string_list2 (void) 
   9 {
  10    GSList *l = NULL;
  11    l = g_slist_append (l, "foo");
  12    l = g_slist_append (l, "bar");
  13    return l;
  14 }

Array length

   1 /**
   2  * gtk_list_store_set_column_types: 
   3  * @store: a #GtkListStore
   4  * @n_columns: Length of @types
   5  * @types: (array length=n_columns): List of types
   6  */
   7 void
   8 gtk_list_store_set_column_types (GtkListStore *list_store,
   9                                  gint          n_columns,
  10                                  GType        *types);

Nullable parameters

   1 /**
   2  * gtk_link_button_new_with_label: 
   3  * @uri: A URI
   4  * @label: (allow-none): A piece of text or NULL
   5  */
   6 GtkWidget *
   7 gtk_link_button_new_with_label (const gchar *uri,
   8                                 const gchar *label);

'out' parameters

   1 /**
   2  * g_file_get_contents:
   3  * @filename: name of a file to read contents from, in the GLib file name encoding
   4  * contents: (out): location to store an allocated string, use g_free() to free the returned string
   5  * length: (out) (allow-none): location to store length in bytes of the contents, or NULL
   6  * error: return location for a GError, or NULL
   7  *
   8  * [...]
   9  *
  10  * Returns: TRUE on success, FALSE if an error occurred
  11  */
  12 gboolean g_file_get_contents (const gchar *filename,
  13                               gchar **contents,
  14                               gsize *length,
  15                               GError **error);
  17 /* this is valid because length has allow-none */
  18 g_file_get_contents ("/etc/motd", &motd, NULL, &error); // VALID
  19 /* but this is not valid, according to those annotations */
  20 g_file_get_contents ("/etc/motd", NULL, NULL, &error); // NOT VALID

G(S)List contained types

   1 /**
   2  * gtk_container_get_children: 
   3  * @container: A #GtkContainer
   4  *
   5  * Return value: (element-type Gtk.Widget) (transfer container): List of #GtkWidget
   6  */
   7 GList*
   8 gtk_container_get_children (GtkContainer *container);


   1 /**
   2  * gtk_widget_get_size_request: 
   3  * @width: (out): Int to store width in
   4  * @height: (out): Int to store height in
   5  */

Out parameters

This is a callee-allocates example; the (out) annotation automatically infers this from the fact that there's a double indirection on a structure parameter.

   1 typedef struct _FooSubObj FooSubObj
   3 /**
   4  * foo_obj_get_sub_obj:
   5  * @obj: A #FooObj
   6  * @subobj: (out): A #FooSubObj
   7  *
   8  * Get a sub object.
   9  */
  10 void
  11 foo_obj_get_sub_obj (FooObj     *obj,
  12                      FooSubObj **subobj)
  13 {
  14   *subobj = foo_sub_object_new ();
  15 }

This is a caller-allocates example; the (out) annotation automatically infers this from the fact that there's only a single indirection on a structure parameter.

   1 typedef struct _FooIter FooIter;
   3 /**
   4  * foo_obj_get_iter:
   5  * @obj: A #FooObj
   6  * @iter: (out): An iterator, will be initialized
   7  *
   8  * Get an iterator.
   9  */
  10 void
  11 foo_obj_get_iter (FooObj *obj,
  12                   FooIter *iter)
  13 {
  14   iter->state = 0;
  15 }

Rename to

Rename to is an advisory annotation. It's not required to fulfill the advisory when generating or making a language binding. The way it is currently implemented, if you rename a function to a name already in use, it will remove the other binding. This is useful to eliminate unwanted/deprecated functions from the binding.

Another (currently unimplemented) use for the rename annotation would be overloading; for example, overloading of constructors or, like in this example, overloading a method to be both an asynchronous and a synchronous one (depending on the amount and what kind of parameters).

   1 /**
   2  * my_type_perform_async:
   3  * @self: The this ptr
   4  * @data: data
   5  * @callback: callback when async operation finished
   6  * @user_data: user_data for @callback
   7  *
   8  * Asynchronously perform
   9  *
  10  * Rename to: my_type_perform
  11  **/
  12 void
  13 my_type_perform_async (MyType *self, gpointer data,
  14                        GFunc callback,
  15                        gpointer user_data);
  17 /**
  18  * my_type_perform:
  19  * @self: The this ptr
  20  * @data: data
  21  *
  22  * Perform
  23  **/
  24 void
  25 my_type_perform (MyType *self, gpointer data);

In a language supporting method overloading, because we advised to rename to perform, and because we have another perform already, this could be bound like this:

   1 class MyType {
   2   public void perform (Pointer data) { }
   3   public void perform (Pointer data, GFunc callback, Pointer user_data) { }
   4 }

However, currently the generated gir/typelib will only contain information about my_type_perform_async, which will shadow (ie, remove) the binding of my_type_perform.


Attributes are arbitrary key/value pairs that can be attached to almost any item including classes, methods, signals, properties, parameters and return values. These attributes appear in both the .gir and the .typelib files. Attributes can serve as a mechanism for software higher in the toolchain. Attributes are name-spaced using dot as a separator. At least one dot must appear in the key name.

   1 /**
   2  * my_frobnicator_poke_path:
   3  * @frobnicator: A #MyFrobnicator
   4  * @object_path: (gdbus.signature o): An object path.
   5  *
   6  * Manipulate an object path.
   7  *
   8  * Returns: (gdbus.signature o): A new object path. Free with g_free().
   9  *
  10  * Attributes: (gdbus.method PokePath)
  11  */
  12 gchar *
  13 my_frobnicator_poke_path (MyFrobnicator *frobnicator,
  14                           const gchar   *object_path)


   1 /**
   2  * MY_CONSTANT:
   3  * A constant.
   4  *
   5  * Value: 100
   6  */
   7 #define MY_CONSTANT 10 * 10

gtk-doc support

If gtk-doc doesn't seem to understand your introspection annotations, you may need to do two things:

  1. make sure you are running gtk-doc >= v1.12 (also try latest version from git)

  2. add '<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>' to your master gtk-doc document; e.g. see the end of tester-docs.xml

Projects/GObjectIntrospection/Annotations/Old (last edited 2013-11-22 19:41:56 by WilliamJonMcCann)