diff options
Diffstat (limited to 'girepository/gitypes.h')
| -rw-r--r-- | girepository/gitypes.h | 30 |
1 files changed, 23 insertions, 7 deletions
diff --git a/girepository/gitypes.h b/girepository/gitypes.h index 78becaef..5ef64ca1 100644 --- a/girepository/gitypes.h +++ b/girepository/gitypes.h @@ -241,13 +241,29 @@ typedef enum /** * GITransfer: - * @GI_TRANSFER_NOTHING: transfer nothing to the caller - * @GI_TRANSFER_CONTAINER: transfer the container (eg list, array, - * hashtable), but no the contents to the caller. - * @GI_TRANSFER_EVERYTHING: transfer everything to the caller. - * - * Represent the transfer ownership information of a #GICallableInfo or - * a #GIArgInfo. + * @GI_TRANSFER_NOTHING: transfer nothing from the callee (function or the type + * instance the property belongs to) to the caller. The callee retains the + * ownership of the transfer and the caller doesn't need to do anything to free + * up the resources of this transfer. + * @GI_TRANSFER_CONTAINER: transfer the container (list, array, hash table) from + * the callee to the caller. The callee retains the ownership of the individual + * items in the container and the caller has to free up the container resources + * (g_list_free()/g_hash_table_destroy() etc) of this transfer. + * @GI_TRANSFER_EVERYTHING: transfer everything, eg the container and its + * contents from the callee to the caller. This is the case when the callee + * creates a copy of all the data it returns. The caller is responsible for + * cleaning up the container and item resources of this transfer. + * + * The transfer is the exchange of data between two parts, from the callee to + * the caller. The callee is either a function/method/signal or an + * object/interface where a property is defined. The caller is the side + * accessing a property or calling a function. + * #GITransfer specifies who's responsible for freeing the resources after the + * ownership transfer is complete. In case of a containing type such as a list, + * an array or a hash table the container itself is specified differently from + * the items within the container itself. Each container is freed differently, + * check the documentation for the types themselves for information on how to + * free them. */ typedef enum { GI_TRANSFER_NOTHING, |