Annotations

Annotations were originally used to help create language bindings by rigorously describing the aspects of a symbol that couldn't be determined automatically. This turned out to be generally useful. So, they are now used for creating API Documentation as well.



Symbol Visibility

Annotation

Applies to

Description

Since

(skip)

identifier

Omit the symbol from the introspected output.

v0.6.4
#556628

parameters
return value

Indicate that the parameter or return value is only useful in C and should be skipped.

v1.29.0
#649657

(rename-to SYMBOL)

identifier

Rename the original symbol's name to SYMBOL. If SYMBOL resolves to a symbol name that is already used, the original binding for that name is removed.

v0.6.3
#556475

Memory and Lifecycle Management

Annotation

Applies to

Description

Since

(transfer MODE)

identifier (only properties)

Transfer ownership for the property, (see below)

v0.9.0
#620484

parameters
return value

Transfer mode for the parameter or return value (see below).

v 0.5.0
unknown

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

Annotation

Applies to

Description

Since

(constructor)

identifier

The annotated symbol should not become available as a static methods but as a constructor.

v0.10.2
#561264

(method)

identifier

This function is a method.

v0.10.2
#639945

(virtual SLOT)

identifier

This function is the invoker for a virtual method.

v0.6.3
#557383

Support for GObject closures

Annotation

Applies to

Description

Since

(destroy)

parameters

The parameter is a "destroy_data" for callbacks.

v0.6.3
#574284

(destroy DESTROY)

parameters

The parameter is a "destroy_data" for callbacks, the DESTROY option points to a paramter name other than destroy_data.

(closure)

parameters

The parameter is a "user_data" for callbacks. Many bindings can pass NULL here.

(closure CLOSURE)

parameters

The parameter is a "user_data" for callbacks, the CLOSURE option points to a different parameter that is the actual callback.

Support for non-GObject Fundamental Objects

Annotation

Applies to

Description

Since

(ref-func FUNC)

identifier

FUNC is the function used to ref a struct, must be a GTypeInstance

v0.9.2
#568913

(unref-func FUNC)

identifier

FUNC is the function used to unref a struct, must be a GTypeInstance

(get-value-func FUNC)

identifier

FUNC is the function used to convert a struct from a GValue, must be a GTypeInstance

(set-value-func FUNC)

identifier

FUNC is the function used to convert from a struct to a GValue, must be a GTypeInstance

Type Signature

Annotation

Applies to

Description

Since

(allow-none)

parameters

For (in) parameters 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.

v 0.5.0
unknown

(in)

parameters

In parameter.

v 0.5.0
unknown

(out)

parameters

Out parameter (automatically determine allocation).

v 0.5.0
unknown

(out caller-allocates)

parameters

Out parameter, where the calling code must allocate storage.

v 0.6.13
#604749

(out callee-allocates)

parameters

Out parameter, where the receiving function must allocate storage.

(inout)

parameters

In/out parameter.

v 0.5.0
unknown

(type TYPE)

identifier

Override the default type, used for properties

v 0.6.2
#546739

parameters
return value

override the parsed C type with given type

(array)

parameters
return value

Arrays.

v 0.5.0
unknown

(array fixed-size=N)

parameters
return value

array of fixed length N

v 0.5.0
unknown

(array length=PARAM)

parameters
return value

array, fetch the length from parameter PARAM

v 0.5.0
unknown

(array zero-terminated=1)

parameters
return value

array which is NULL terminated

v 0.6.0
#557786

(element-type TYPE)

parameters
return value

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

v 0.5.0
unknown

(element-type KTYPE VTYPE)

parameters
return value

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

v 0.5.0
unknown

(foreign)

identifier

The annotated symbol is a foreign struct, meaning it is not available in a g-i supported library.

v0.6.12
#619450

(scope TYPE)

parameters

The parameter is a callback, the TYPE option indicates the lifetime 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.

v0.6.2
#556489

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:

  • (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)

Data Annotations

Annotation

Applies to

Description

Since

(value VALUE)

identifier

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

v 0.5.0
unknown

(attributes my.key=val my.key2)

identifier
parameters
return value

Attributes are free-form "key=value" annotations. When present, at least one key has to be specified. Assigning values to keys is optional.

v 0.9.0
#571548

Deprecated GObject-Introspection Annotations

Annotation

Description

Since

(null-ok)

Replaced by (allow-none)

v 0.6.0
#557405

(in-out)

Replaced by (inout)

1.39.0
#688897

Possible Future GObject-Introspection Annotations

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

Annotation

Applies to

Description

Bug report

(default VALUE)

parameters

Default value for a parameter.

#558620

(error-domains DOM1 DOM2)

parameters

Typed errors, similar to throws in Java.

unknown

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

Instances:

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

Examples

See a number of examples of using annotations.

Projects/GTK+/DocumentationSyntax/Annotations (last edited 2014-02-09 14:04:15 by WilliamJonMcCann)