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:
Syntax |
Description |
(out) |
out parameter |
(in) |
in parameter |
(inout) |
in/out parameter |
(allow-none) |
NULL is ok, both for passing and for returning |
(default VALUE) |
default value for a parameter Not implemented yet: bug |
(not-error) |
a GError parameter is not to be handled like a normal GError Not implemented yet |
(error-domains DOM1 DOM2) |
Typed errors. Similar to throws in Java Not implemented yet |
Per parameter or return value:
Syntax |
Description |
(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) |
arrays |
(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) |
specifies the type Not yet implemented |
Syntax |
Description |
Free-function: SYMBOL |
Function to free a caller-owns returned value. Not implemented yet |
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. |
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.
