Anotaciones de introspección de GObject
El comentario de GTK-Doc para la función myapp_spell_checker_get_suggestions() contiene anotaciones de GObject Introspection para el valor de retorno:
/**
* ...
* Returns: (transfer full) (element-type utf8): la lista de sugerencias.
*/
El tipo de retorno de la función es GSList *, que no es suficiente para que los enlaces de idioma sepan qué contiene la lista, y cómo liberarla. (transferencia completa) significa que la persona que llama debe liberar completamente el valor de retorno: la lista misma y sus elementos. (tipo de elemento utf8) significa que la lista contiene cadenas UTF-8.
Para obtener un valor de retorno, si la anotación de transferencia es contenedor de transferencia, la persona que llama necesita liberar solo la estructura de datos, no sus elementos. Y si la anotación de transferencia es transferir ninguna, la propiedad del contenido variable no se transfiere y, por lo tanto, la persona que llama no debe liberar el valor de retorno.
Hay muchas otras anotaciones de GObject Introspection (GI), por nombrar solo un par de otras:
(nullable): el valor puede serNULL;(out): un parámetro de función "out", es decir, un parámetro que devuelve un valor.
Como puede ver, las anotaciones GI no solo son útiles para los enlaces de idiomas, sino que también recopilan información útil para el programador de C.
Para obtener una lista completa de anotaciones GI, consulte la wiki de GObject Introspection .