You may wish to see Projects/GTK+/DocumentationSyntax instead.

GObject-Introspection Annotations

GTK-Doc Format Primer

GObject-Introspection annotations are built on top of GTK-Doc comment blocks. These are plain old C comment blocks, but formatted in a special way. Each GTK-Doc comment block starts with a /** on its own line end ends with */, again on its own line.

The basic format of a GTK-Doc comment block looks like this:

   1  /**
   2   * identifier_name: (annotations)
   3   * @parameter_name: (annotations): description
   4   *
   5   * symbol description
   6   *
   7   * tag_name: (annotations): description
   8   */

As we can see, a GTK-Doc comment block can be broken down into a couple of parts. Each part is built out of one or more fields, separated by a : character. Each part has to start on its own line. Fields cannot span multiple lines except the various description fields.

The order in which parts are written is important. For example, putting a tag part before the symbol description part is invalid as it would result in the symbol description to be mistaken for the tag description.

In the above example we have:

• the start of a GTK-Doc comment block on line 1
• the identifier part on line 2
• a parameter part on line 3
• the symbol description on line 5
• a tag part on line 7
• the end of the comment block on line 8

identifier part

   1  /**
   2   * identifier_name: (annotations)
   3   * ...
   4   */

The identifier part is required as it identifies the symbol you want to annotate. It is always written on the line immediately following the start of your GTK-Doc comment block (/**).

The identifier part is constructed from:

• a required identifier_name field

  • different kinds of symbols that can be documented and annotated are described in the

    GTK-Doc manual.

• an optional annotations field

parameter part

   1  /**
   2   * ...
   3   * @parameter_name: (annotations): description
   4   * ...
   5   */

The parameter part is optional. This means that there can be 0 or more parameters, depending on the symbol you are annotating.

parameter parts are constructed from:

• a required parameter_name which starts with a @ character

  • this name should correspond with the parameter name of you function's signature.

• an optional annotations field

• a required description field (can be "empty")
  • can contain a single paragraph (multiple lines but no empty lines) of text.

Note that multiple parameter parts are never separated by an empty line.

symbol description part

   1  /**
   2   * ...
   3   *
   4   * symbol description
   5   * ...
   6   */

The symbol description part is optional. When present, it must always be preceded with an empty line. It can contain multiple paragraphs (multiple lines and empty lines) describing what the function, property, signal, enum or constant does.

tag part

   1  /**
   2   * ...
   3   * tag_name: (annotations)||value: description
   4   * ...
   5   */

The tag part is optional. There can be 0 or more tags, depending on the symbol you are annotating.

tag parts are constructed from:

• a required tag_name

  • There are only four valid tags: Returns, Since, Deprecated, and Stability.

• an optional annotations field (Returns)
  OR
  an optional value field (Since, Deprecated, and Stability)

• a required description field (can be "empty")
  • can contain multiple paragraphs (multiple lines and empty lines) of text.

tag parts can safely be preceded or followed by an empty line.

Tags taking an optional value field accept the following values:

GObject-Introspection annotations

Symbol visibility

Memory and lifecycle management

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.

Support for GObject objects

Support for GObject closures

Support for non-GObject fundamental objects

Type signature

Scope types:

• 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 invocation. Can only be called once.

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

An example of a function using the call scope is g_slist_foreach(). For async there is g_file_read_async() and for notified g_idle_add_full().

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

• (in) parameters: (transfer none)

• (inout) and (out) parameters: (transfer full)

  • if (caller allocates) is set: (transfer none)

• gchar* means (type utf8)

• return values: (transfer full)

  • gchar* means (type utf8) (transfer full)

  • const gchar* means (type utf8) (transfer none)

  • GObject* defaults to (transfer full)

Data annotations

Deprecated GObject-Introspection annotations

Possible future GObject-Introspection annotations

These proposed additions are currently being discussed and in various stages of development.

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 (see below)
• guint8 array: binary data

Filename type:

• The filename type represents an utf-8 string on Windows and a zero terminated guint8 array on Unix. It should be used for filenames, environment variables and process arguments.

Reference to Object Instances

Instances:

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

Examples

Transfer

   1 /**
   2  * mylib_get_constant1:
   3  *
   4  * Returns: (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  * Returns: (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  * Returns: (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  * Returns: (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

A number of things are nullable by convention, which means that you do not have to add a (nullable) annotation to your code for them to be marked as nullable in a GIR file. If you need to mark a parameter or return value as not nullable, use (not nullable) to override the convention. Conventionally, the following are automatically nullable:

• (closure) parameters and their corresponding user data parameters

• gpointer parameters and return types, unless also annotated with (type)

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

   1 /**
   2  * g_source_add_unix_fd:
   3  * @source: a #GSource
   4  * @fd: the fd to monitor
   5  * @events: an event mask
   6  *
   7  * Returns: (not nullable): an opaque tag
   8  */
   9 gpointer
  10 g_source_add_unix_fd (GSource      *source,
  11                       gint          fd,
  12                       GIOCondition  events);
  13 
  14 /**
  15  * g_source_remove_unix_fd:
  16  * @source: a #GSource
  17  * @tag: (not nullable): the tag from g_source_add_unix_fd()
  18  */
  19 void
  20 g_source_remove_unix_fd (GSource  *source,
  21                          gpointer  tag);

G(S)List contained types

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

   1 /**
   2  * FooBar:alist: (type GSList(NiceObj))
   3  *
   4  * This property is a GSList of NiceObj GOjects.
   5  */
   6     g_object_class_install_property (object_class,
   7                                      FOO_BAR_PROP_ALIST,
   8                                      g_param_spec_pointer ("alist",
   9                                                            "Alist",
  10                                                            "A list of nice objects",
  11                                                            G_PARAM_READWRITE));

Direction

   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
   2 
   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;
   2 
   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 }

An example which demonstrates an (optional) parameter: an (out) parameter where the caller can pass NULL if they don’t want to receive the (out) value.

   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) (optional): 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);
  16 
  17 /* this is valid because length has (optional) */
  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
  21 

g_hash_table_iter_next() demonstrates the difference between (nullable) and (optional) for (out) parameters. For an (out) parameter, (optional) indicates that NULL may be passed by the caller to indicate they don’t want to receive the (out) value. (nullable) indicates that NULL may be passed out by the callee as the returned value.

   1 /**
   2  * g_hash_table_iter_next:
   3  * @iter: an initialized #GHashTableIter
   4  * @key: (out) (optional): a location to store the key
   5  * @value: (out) (optional) (nullable): a location to store the value
   6  *
   7  * [...]
   8  *
   9  * Returns: %FALSE if the end of the #GHashTable has been reached.
  10  */
  11 gboolean
  12 g_hash_table_iter_next (GHashTableIter *iter,
  13                         gpointer       *key,
  14                         gpointer       *value);
  15 
  16 /* this is valid because value and key have (optional) */
  17 g_hash_table_iter_next (iter, NULL, NULL);
  18 
  19 gpointer key, value;
  20 g_hash_table_iter_next (iter, &key, &value);
  21 
  22 if (value == NULL)
  23   /* this is valid because value has (nullable) */
  24 if (key == NULL)
  25   /* this is NOT VALID because key does not have (nullable) */

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: (rename-to my_type_perform)
   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 void
  11 my_type_perform_async (MyType *self, gpointer data,
  12                        GFunc callback,
  13                        gpointer user_data);
  14 
  15 /**
  16  * my_type_perform:
  17  * @self: The this ptr
  18  * @data: data
  19  *
  20  * Perform
  21  **/
  22 void
  23 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

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: (attributes gdbus.method PokePath)
   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 gchar *
  11 my_frobnicator_poke_path (MyFrobnicator *frobnicator,
  12                           const gchar   *object_path)

Constants

   1 /**
   2  * MY_CONSTANT: (value 100)
   3  * A constant.
   4  */
   5 #define MY_CONSTANT 10 * 10
   6 

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