Introspection gtk-doc annotations

Annotation syntax

The basic syntax looks like this:

 /**
  * lib_symbol_name:
  *
  * @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, the annotations will not be included without it.

There are more illustrative examples below.

Table of possible annotations

Per parameter:

Per parameter or return value:

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.

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.