Introspection gtk-doc annotations

Annotation syntax

The basic syntax looks like this:

 /**
  * lib_symbol_name: (annotation1) (annotation2)
  *
  * @param_first: (annotation1) (annotation2) (...): documentation for first 
  * @param_second: (annotation1) (annotation2) (...): documentation for second
  *
  * Returns: (annotation1) (annotation2) (...): Returns stuff which you have to free after use
  */

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.

There are more illustrative examples below.

Table of possible annotations

In function/type header:

Per parameter:

Per parameter or return value:

Additional gtk-doc headings:

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.

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.

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.

  • async - Only valid for the duration of the first callback invokation.

  • notified - valid until the GDestroyNotify argument 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 values:

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)
• Parameters passed by reference ("int *", "double *") are treated as out parameters with the exception of strings.

Basic types:

• any: pointer to anything
• boolean:boolean
• int[8,16,32,64]: integer
• uint[8,16,32,64]: unsigned integer
• long: long
• ulong: unsigned long
• ssize_t: ssize
• size_t: size
• time_t: time
• GType: a gtype
• float: float
• double: double
• utf8: string encoded in utf8
• filename: filename string

Instances:

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

Annotation examples

Transfer

/**
 * mylib_get_constant1:
 *
 * Return value: (transfer full): a constant, free when you used it
 */
gchar *
mylib_get_constant1 (void) 
{
   return g_strdup("a constant");
}

/**
 * mylib_get_constant2:
 *
 * Return value: (transfer none): another constant
 */
const gchar *
mylib_get_string2 (void) 
{
   return "another constant";
}

/**
 * mylib_get_string_list1:
 *
 * Return value: (element-type utf8) (transfer full): list of constants,
 *               free the list with g_slist_free and the elements with g_free when done.
 */
GSList *
mylib_get_string_list1 (void) 
{
   GSList *l = NULL;
   l = g_slist_append (l, g_strdup ("foo"));
   l = g_slist_append (l, g_strdup ("bar"));
   return l;
}

/**
 * mylib_get_string_list2:
 *
 * Return value: (element-type utf8) (transfer container): list of constants
 *               free the list with g_slist_free when done. 
 */
GSList *
mylib_get_string_list2 (void) 
{
   GSList *l = NULL;
   l = g_slist_append (l, "foo");
   l = g_slist_append (l, "bar");
   return l;
}

Array length

/**
 * gtk_list_store_set_column_types: 
 * @store: a #GtkListStore
 * @n_columns: Length of @types
 * @types: (array length=n_columns): List of types
 */
void
gtk_list_store_set_column_types (GtkListStore *list_store,
                                 gint          n_columns,
                                 GType        *types);

Nullable parameters

/**
 * gtk_link_button_new_with_label: 
 * @uri: A URI
 * @label: (allow-none): A piece of text or NULL
 */
GtkWidget *
gtk_link_button_new_with_label (const gchar *uri,
                                const gchar *label);

G(S)List contained types

/**
 * gtk_container_get_children: 
 * @container: A #GtkContainer
 *
 * Return value: (element-type Gtk.Widget) (transfer container): List of #GtkWidget
 */
GList*
gtk_container_get_children (GtkContainer *container);

Direction

/**
 * gtk_widget_get_size_request: 
 * @width: (out): Int to store width in
 * @height: (out): Int to store height in
 */

Rename to

About

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

/**
 * my_type_perform_async:
 * @self: The this ptr
 * @data: data
 * @callback: callback when async operation finished
 * @user_data: user_data for @callback
 *
 * Asynchronously perform
 *
 * Rename to: my_type_perform
 **/
void
my_type_perform_async (MyType *self, gpointer data,
                       GFunc callback,
                       gpointer user_data);

/**
 * my_type_perform:
 * @self: The this ptr
 * @data: data
 *
 * Perform
 **/
void
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:

class MyType {
  public void perform (Pointer data) { }
  public void perform (Pointer data, GFunc callback, Pointer user_data) { }
}

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.

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 (possibly 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