Explain how the return value of the (transfer full) methods should be freed. I also made some cosmetic changes in the API doc of some of the files as I was modifying them. --- libvirt-gconfig/libvirt-gconfig-domain-os.c | 11 ++- libvirt-gconfig/libvirt-gconfig-domain.c | 28 ++++-- libvirt-gobject/libvirt-gobject-connection.c | 94 +++++++++++++------- libvirt-gobject/libvirt-gobject-domain-device.c | 8 +- libvirt-gobject/libvirt-gobject-domain-disk.c | 4 +- libvirt-gobject/libvirt-gobject-domain-interface.c | 4 +- libvirt-gobject/libvirt-gobject-domain-snapshot.c | 4 +- libvirt-gobject/libvirt-gobject-domain.c | 16 ++-- libvirt-gobject/libvirt-gobject-interface.c | 3 +- libvirt-gobject/libvirt-gobject-manager.c | 8 +- libvirt-gobject/libvirt-gobject-network-filter.c | 4 +- libvirt-gobject/libvirt-gobject-network.c | 3 +- libvirt-gobject/libvirt-gobject-node-device.c | 4 +- libvirt-gobject/libvirt-gobject-secret.c | 4 +- libvirt-gobject/libvirt-gobject-storage-pool.c | 19 ++-- libvirt-gobject/libvirt-gobject-storage-vol.c | 6 +- 16 files changed, 157 insertions(+), 63 deletions(-) diff --git a/libvirt-gconfig/libvirt-gconfig-domain-os.c b/libvirt-gconfig/libvirt-gconfig-domain-os.c index 6e3cabd..9a1648a 100644 --- a/libvirt-gconfig/libvirt-gconfig-domain-os.c +++ b/libvirt-gconfig/libvirt-gconfig-domain-os.c @@ -83,6 +83,7 @@ void gvir_config_domain_os_set_os_type(GVirConfigDomainOs *os, /** * gvir_config_domain_os_set_kernel: + * @os: a #GVirConfigDomainOs * @kernel: (allow-none): The kernel path */ void gvir_config_domain_os_set_kernel(GVirConfigDomainOs *os, @@ -94,6 +95,7 @@ void gvir_config_domain_os_set_kernel(GVirConfigDomainOs *os, /** * gvir_config_domain_os_set_ramdisk: + * @os: a #GVirConfigDomainOs * @ramdisk: (allow-none): The ramdisk path */ void gvir_config_domain_os_set_ramdisk(GVirConfigDomainOs *os, @@ -105,6 +107,7 @@ void gvir_config_domain_os_set_ramdisk(GVirConfigDomainOs *os, /** * gvir_config_domain_os_set_cmdline: + * @os: a #GVirConfigDomainOs * @cmdline: (allow-none): The direct boot commandline */ void gvir_config_domain_os_set_cmdline(GVirConfigDomainOs *os, @@ -116,6 +119,7 @@ void gvir_config_domain_os_set_cmdline(GVirConfigDomainOs *os, /** * gvir_config_domain_os_set_init: + * @os: a #GVirConfigDomainOs * @init: (allow-none): */ void gvir_config_domain_os_set_init(GVirConfigDomainOs *os, @@ -127,6 +131,7 @@ void gvir_config_domain_os_set_init(GVirConfigDomainOs *os, /** * gvir_config_domain_os_set_loader: + * @os: a #GVirConfigDomainOs * @loader: (allow-none): */ void gvir_config_domain_os_set_loader(GVirConfigDomainOs *os, @@ -183,6 +188,7 @@ void gvir_config_domain_os_set_smbios_mode(GVirConfigDomainOs *os, /** * gvir_config_domain_os_set_boot_devices: + * @os: a #GVirConfigDomainOs * @boot_devices: (in) (element-type LibvirtGConfig.DomainOsBootDevice): */ void gvir_config_domain_os_set_boot_devices(GVirConfigDomainOs *os, GList *boot_devices) @@ -246,8 +252,11 @@ static gboolean add_boot_device(xmlNodePtr node, gpointer opaque) /** * gvir_config_domain_os_get_boot_devices: + * @os: a #GVirConfigDomainOs * - * Gets the list of devices attached to @os + * Gets the list of devices attached to @os. The returned list should be + * freed with g_list_free(), after its elements have been unreffed with + * g_object_unref(). * * Returns: (element-type LibvirtGConfig.DomainOsBootDevice) (transfer full): * a newly allocated #GList of #GVirConfigDomainOsBootDevice. diff --git a/libvirt-gconfig/libvirt-gconfig-domain.c b/libvirt-gconfig/libvirt-gconfig-domain.c index 9076a76..b6b43f0 100644 --- a/libvirt-gconfig/libvirt-gconfig-domain.c +++ b/libvirt-gconfig/libvirt-gconfig-domain.c @@ -206,6 +206,7 @@ const char *gvir_config_domain_get_name(GVirConfigDomain *domain) /** * gvir_config_domain_set_name: + * @domain: a #GVirConfigDomain * @name: (allow-none): */ void gvir_config_domain_set_name(GVirConfigDomain *domain, const char *name) @@ -223,6 +224,7 @@ const char *gvir_config_domain_get_description(GVirConfigDomain *domain) /** * gvir_config_domain_set_description: + * @domain: a #GVirConfigDomain * @description: (allow-none): */ void gvir_config_domain_set_description(GVirConfigDomain *domain, const char *description) @@ -234,7 +236,7 @@ void gvir_config_domain_set_description(GVirConfigDomain *domain, const char *de /** * gvir_config_domain_get_memory: - * @domain: A domain configuration object. + * @domain: a #GVirConfigDomain * * Returns: amount of RAM in kilobytes (i.e. blocks of 1024 bytes). */ @@ -246,7 +248,7 @@ guint64 gvir_config_domain_get_memory(GVirConfigDomain *domain) /** * gvir_config_domain_set_memory: - * @domain: A domain configuration object. + * @domain: a #GVirConfigDomain * @memory: The amount of RAM in kilobytes. * * Sets the amount of RAM allocated to @domain in kilobytes (i.e. blocks of 1024 bytes). @@ -285,8 +287,11 @@ static gboolean add_feature(xmlNodePtr node, gpointer opaque) /** * gvir_config_domain_get_features: + * @domain: a #GVirConfigDomain * - * Returns: (transfer full): + * Returns: (transfer full): The returned list should be freed with + * g_strfreev() when no longer needed. + */ GStrv gvir_config_domain_get_features(GVirConfigDomain *domain) { @@ -323,6 +328,7 @@ void gvir_config_domain_set_features(GVirConfigDomain *domain, /** * gvir_config_domain_set_clock: + * @domain: a #GVirConfigDomain * @klock: (allow-none): */ void gvir_config_domain_set_clock(GVirConfigDomain *domain, @@ -338,10 +344,12 @@ void gvir_config_domain_set_clock(GVirConfigDomain *domain, /** * gvir_config_domain_get_os: + * @domain: a #GVirConfigDomain * * Gets the operating system configuration of @domain * - * Returns: (transfer full): + * Returns: (transfer full): A #GVirConfigDomainOs. The returned + * object should be unreffed with g_object_unref() when no longer needed. */ GVirConfigDomainOs *gvir_config_domain_get_os(GVirConfigDomain *domain) { @@ -358,7 +366,8 @@ GVirConfigDomainOs *gvir_config_domain_get_os(GVirConfigDomain *domain) /** * gvir_config_domain_set_os: - * @os: (allow-none): + * @domain: a #GVirConfigDomain + * @os: (allow-none): the os configuration to set */ void gvir_config_domain_set_os(GVirConfigDomain *domain, GVirConfigDomainOs *os) @@ -373,7 +382,8 @@ void gvir_config_domain_set_os(GVirConfigDomain *domain, /** * gvir_config_domain_set_seclabel: - * @seclabel: (allow-none): + * @domain: a #GVirConfigDomain + * @seclabel: (allow-none): the security label configuration to set */ void gvir_config_domain_set_seclabel(GVirConfigDomain *domain, GVirConfigDomainSeclabel *seclabel) @@ -410,6 +420,7 @@ void gvir_config_domain_set_lifecycle(GVirConfigDomain *domain, /** * gvir_config_domain_set_devices: + * @domain: a #GVirConfigDomain * @devices: (in) (element-type LibvirtGConfig.DomainDevice): */ void gvir_config_domain_set_devices(GVirConfigDomain *domain, @@ -480,8 +491,11 @@ static gboolean add_device(xmlNodePtr node, gpointer opaque) /** * gvir_config_domain_get_devices: + * @domain: a #GVirConfigDomain * - * Gets the list of devices attached to @domain + * Gets the list of devices attached to @domain. The returned list should + * be freed with g_list_free(), after its elements have been unreffed with + * g_object_unref(). * * Returns: (element-type LibvirtGConfig.DomainDevice) (transfer full): * a newly allocated #GList of #GVirConfigDomainDevice. diff --git a/libvirt-gobject/libvirt-gobject-connection.c b/libvirt-gobject/libvirt-gobject-connection.c index 6469ebc..b12669d 100644 --- a/libvirt-gobject/libvirt-gobject-connection.c +++ b/libvirt-gobject/libvirt-gobject-connection.c @@ -400,7 +400,7 @@ static int domain_event_cb(virConnectPtr conn G_GNUC_UNUSED, /** * gvir_connection_open: - * @conn: the connection + * @conn: a #GVirConnection * @cancellable: (allow-none)(transfer none): cancellation object */ gboolean gvir_connection_open(GVirConnection *conn, @@ -474,7 +474,7 @@ gvir_connection_open_helper(GSimpleAsyncResult *res, /** * gvir_connection_open_async: - * @conn: the connection + * @conn: a #GVirConnection * @cancellable: (allow-none)(transfer none): cancellation object * @callback: (scope async): completion callback * @user_data: (closure): opaque data for callback @@ -500,7 +500,7 @@ void gvir_connection_open_async(GVirConnection *conn, /** * gvir_connection_open_finish: - * @conn: the connection + * @conn: a #GVirConnection * @result: (transfer none): async method result */ gboolean gvir_connection_open_finish(GVirConnection *conn, @@ -606,7 +606,7 @@ error: /** * gvir_connection_fetch_domains: - * @conn: the connection + * @conn: a #GVirConnection * @cancellable: (allow-none)(transfer none): cancellation object */ gboolean gvir_connection_fetch_domains(GVirConnection *conn, @@ -735,7 +735,7 @@ cleanup: /** * gvir_connection_fetch_storage_pools: - * @conn: the connection + * @conn: a #GVirConnection * @cancellable: (allow-none)(transfer none): cancellation object */ gboolean gvir_connection_fetch_storage_pools(GVirConnection *conn, @@ -879,7 +879,7 @@ gvir_connection_fetch_domains_helper(GSimpleAsyncResult *res, /** * gvir_connection_fetch_domains_async: - * @conn: the connection + * @conn: a #GVirConnection * @cancellable: (allow-none)(transfer none): cancellation object * @callback: (scope async): completion callback * @user_data: (closure): opaque data for callback @@ -904,7 +904,7 @@ void gvir_connection_fetch_domains_async(GVirConnection *conn, /** * gvir_connection_fetch_domains_finish: - * @conn: the connection + * @conn: a #GVirConnection * @result: (transfer none): async method result */ gboolean gvir_connection_fetch_domains_finish(GVirConnection *conn, @@ -938,7 +938,7 @@ gvir_connection_fetch_pools_helper(GSimpleAsyncResult *res, /** * gvir_connection_fetch_storage_pools_async: - * @conn: the connection + * @conn: a #GVirConnection * @cancellable: (allow-none)(transfer none): cancellation object * @callback: (scope async): completion callback * @user_data: (closure): opaque data for callback @@ -963,7 +963,7 @@ void gvir_connection_fetch_storage_pools_async(GVirConnection *conn, /** * gvir_connection_fetch_storage_pools_finish: - * @conn: the connection + * @conn: a #GVirConnection * @result: (transfer none): async method result */ gboolean gvir_connection_fetch_storage_pools_finish(GVirConnection *conn, @@ -994,8 +994,13 @@ static void gvir_domain_ref(gpointer obj, gpointer ignore G_GNUC_UNUSED) /** * gvir_connection_get_domains: + * @conn: a #GVirConnection * - * Return value: (element-type LibvirtGObject.Domain) (transfer full): List of #GVirDomain + * Gets a list of the domains available through @conn. + * + * Return value: (element-type LibvirtGObject.Domain) (transfer full): List + * of #GVirDomain. The returned list should be freed with g_list_free(), + * after its elements have been unreffed with g_object_unref(). */ GList *gvir_connection_get_domains(GVirConnection *conn) { @@ -1014,9 +1019,14 @@ GList *gvir_connection_get_domains(GVirConnection *conn) /** * gvir_connection_get_storage_pools: + * @conn: a #GVirConnection + * + * Gets a list of the storage pools available through @conn. * * Return value: (element-type LibvirtGObject.StoragePool) (transfer full): List - * of #GVirStoragePool + * of #GVirStoragePool. The returned list should be freed with + * g_list_free(), after its elements have been unreffed with + * g_object_unref(). */ GList *gvir_connection_get_storage_pools(GVirConnection *conn) { @@ -1035,9 +1045,11 @@ GList *gvir_connection_get_storage_pools(GVirConnection *conn) /** * gvir_connection_get_domain: + * @conn: a #GVirConnection * @uuid: uuid string of the requested domain * - * Return value: (transfer full): the #GVirDomain, or NULL + * Return value: (transfer full): the #GVirDomain, or NULL. The returned + * object should be unreffed with g_object_unref() when no longer needed. */ GVirDomain *gvir_connection_get_domain(GVirConnection *conn, const gchar *uuid) @@ -1054,9 +1066,11 @@ GVirDomain *gvir_connection_get_domain(GVirConnection *conn, /** * gvir_connection_get_storage_pool: + * @conn: a #GVirConnection * @uuid: uuid string of the requested storage pool * - * Return value: (transfer full): the #GVirStoragePool, or NULL + * Return value: (transfer full): the #GVirStoragePool, or NULL. The returned + * object should be unreffed with g_object_unref() when no longer needed. */ GVirStoragePool *gvir_connection_get_storage_pool(GVirConnection *conn, const gchar *uuid) @@ -1075,9 +1089,11 @@ GVirStoragePool *gvir_connection_get_storage_pool(GVirConnection *conn, /** * gvir_connection_find_domain_by_id: + * @conn: a #GVirConnection * @id: id of the requested domain * - * Return value: (transfer full): the #GVirDomain, or NULL + * Return value: (transfer full): the #GVirDomain, or NULL. The returned + * object should be unreffed with g_object_unref() when no longer needed. */ GVirDomain *gvir_connection_find_domain_by_id(GVirConnection *conn, gint id) @@ -1107,9 +1123,11 @@ GVirDomain *gvir_connection_find_domain_by_id(GVirConnection *conn, /** * gvir_connection_find_domain_by_name: + * @conn: a #GVirConnection * @name: name of the requested domain * - * Return value: (transfer full): the #GVirDomain, or NULL + * Return value: (transfer full): the #GVirDomain, or NULL. The returned + * object should be unreffed with g_object_unref() when no longer needed. */ GVirDomain *gvir_connection_find_domain_by_name(GVirConnection *conn, const gchar *name) @@ -1141,9 +1159,11 @@ GVirDomain *gvir_connection_find_domain_by_name(GVirConnection *conn, /** * gvir_connection_find_storage_pool_by_name: + * @conn: a #GVirConnection * @name: name of the requested storage pool * - * Return value: (transfer full): the #GVirStoragePool, or NULL + * Return value: (transfer full): the #GVirStoragePool, or NULL. The returned + * object should be unreffed with g_object_unref() when no longer needed. */ GVirStoragePool *gvir_connection_find_storage_pool_by_name(GVirConnection *conn, const gchar *name) @@ -1193,9 +1213,11 @@ G_DEFINE_BOXED_TYPE(GVirConnectionHandle, gvir_connection_handle, /** * gvir_connection_get_stream: + * @conn: a #GVirConnection * @flags: flags to use for the stream * - * Return value: (transfer full): a #GVirStream stream, or NULL + * Return value: (transfer full): a #GVirStream stream, or NULL.The returned + * object should be unreffed with g_object_unref() when no longer needed. */ GVirStream *gvir_connection_get_stream(GVirConnection *self, guint flags) @@ -1215,13 +1237,15 @@ GVirStream *gvir_connection_get_stream(GVirConnection *self, /** * gvir_connection_create_domain: - * @conn: the connection on which to create the domain + * @conn: a #GVirConnection on which to create the domain * @conf: the configuration for the new domain * * Create the configuration file for a new persistent domain. * The returned domain will initially be in the shutoff state. * - * Returns: (transfer full): the newly created domain + * Returns: (transfer full): the newly created domain, or NULL if an error + * occurred. The returned object should be unreffed with g_object_unref() + * when no longer needed. */ GVirDomain *gvir_connection_create_domain(GVirConnection *conn, GVirConfigDomain *conf, @@ -1261,13 +1285,15 @@ GVirDomain *gvir_connection_create_domain(GVirConnection *conn, /** * gvir_connection_start_domain: - * @conn: the connection on which to create the domain + * @conn: a #GVirConnection on which to create the domain * @conf: the configuration for the new domain * * Start a new transient domain without persistent configuration. * The returned domain will initially be running. * - * Returns: (transfer full): the newly created domain + * Returns: (transfer full): the newly created domain, or NULL if an error + * occurred. The returned object should be unreffed with g_object_unref() + * when no longer needed. */ GVirDomain *gvir_connection_start_domain(GVirConnection *conn, GVirConfigDomain *conf, @@ -1308,12 +1334,14 @@ GVirDomain *gvir_connection_start_domain(GVirConnection *conn, /** * gvir_connection_create_storage_pool: - * @conn: the connection on which to create the pool + * @conn: a #GVirConnection on which to create the pool * @conf: the configuration for the new storage pool * @flags: the flags * @err: return location for any #GError * - * Returns: (transfer full): the newly created storage pool + * Returns: (transfer full): the newly created storage pool, or NULL if an + * error occurred. The returned list should be freed with g_list_free(), + * after its elements have been unreffed with g_object_unref(). */ GVirStoragePool *gvir_connection_create_storage_pool (GVirConnection *conn, @@ -1352,10 +1380,12 @@ GVirStoragePool *gvir_connection_create_storage_pool /** * gvir_connection_get_node_info: - * @conn: the connection + * @conn: a #GVirConnection * @err: return location for any #GError * - * Returns: (transfer full): the info + * Returns: (transfer full): the info, or NULL if an error occurred. The + * returned object should be unreffed with g_object_unref() when no longer + * needed. */ GVirNodeInfo *gvir_connection_get_node_info(GVirConnection *conn, GError **err) @@ -1386,10 +1416,12 @@ GVirNodeInfo *gvir_connection_get_node_info(GVirConnection *conn, /** * gvir_connection_get_capabilities: - * @conn: the connection + * @conn: a #GVirConnection * @err: return location for any #GError * - * Return value: (transfer full): a #GVirConfigCapabilities or NULL + * Return value: (transfer full): a #GVirConfigCapabilities or NULL. The + * returned object should be unreffed with g_object_unref() when no longer + * needed. */ GVirConfigCapabilities *gvir_connection_get_capabilities(GVirConnection *conn, GError **err) @@ -1436,7 +1468,7 @@ gvir_connection_get_capabilities_helper(GSimpleAsyncResult *res, /** * gvir_connection_get_capabilities_async: - * @conn: the connection + * @conn: a #GVirConnection * @cancellable: (allow-none)(transfer none): cancellation object * @callback: (scope async): completion callback * @user_data: (closure): opaque data for callback @@ -1461,10 +1493,12 @@ void gvir_connection_get_capabilities_async(GVirConnection *conn, /** * gvir_connection_get_capabilities_finish: - * @conn: the connection + * @conn: a #GVirConnection * @result: (transfer none): async method result * - * Return value: (transfer full): a #GVirConfigCapabilities or NULL. + * Return value: (transfer full): a #GVirConfigCapabilities or NULL. The + * returned object should be unreffed with g_object_unref() when no longer + * needed. */ GVirConfigCapabilities * gvir_connection_get_capabilities_finish(GVirConnection *conn, diff --git a/libvirt-gobject/libvirt-gobject-domain-device.c b/libvirt-gobject/libvirt-gobject-domain-device.c index db50c09..9a65468 100644 --- a/libvirt-gobject/libvirt-gobject-domain-device.c +++ b/libvirt-gobject/libvirt-gobject-domain-device.c @@ -161,7 +161,9 @@ virDomainPtr gvir_domain_device_get_domain_handle(GVirDomainDevice *self) * gvir_domain_device_get_domain: * @device: the domain device * - * Returns: (transfer full): the associated domain + * Returns: (transfer full): the associated domain. The returned object + * should be unreffed with g_object_unref() when no longer needed. + */ GVirDomain *gvir_domain_device_get_domain(GVirDomainDevice *device) { @@ -172,7 +174,9 @@ GVirDomain *gvir_domain_device_get_domain(GVirDomainDevice *device) * gvir_domain_device_get_config: * @device: the domain device * - * Returns: (transfer full): the config + * Returns: (transfer full): the config. The returned object should be + * unreffed with g_object_unref() when no longer needed. + */ GVirConfigDomainDevice *gvir_domain_device_get_config(GVirDomainDevice *device) { diff --git a/libvirt-gobject/libvirt-gobject-domain-disk.c b/libvirt-gobject/libvirt-gobject-domain-disk.c index fb85328..607e26c 100644 --- a/libvirt-gobject/libvirt-gobject-domain-disk.c +++ b/libvirt-gobject/libvirt-gobject-domain-disk.c @@ -112,7 +112,9 @@ static const gchar *gvir_domain_disk_get_path(GVirDomainDisk *self) * within the stats structure may be returned as -1, which indicates * that the hypervisor does not support that particular statistic. * - * Returns: (transfer full): the stats or %NULL in case of error + * Returns: (transfer full): the stats or %NULL in case of error.The + * returned object should be unreffed with g_object_unref() when no longer + * needed. **/ GVirDomainDiskStats *gvir_domain_disk_get_stats(GVirDomainDisk *self, GError **err) { diff --git a/libvirt-gobject/libvirt-gobject-domain-interface.c b/libvirt-gobject/libvirt-gobject-domain-interface.c index 9f4b30d..7087cbc 100644 --- a/libvirt-gobject/libvirt-gobject-domain-interface.c +++ b/libvirt-gobject/libvirt-gobject-domain-interface.c @@ -114,7 +114,9 @@ static const gchar *gvir_domain_interface_get_path(GVirDomainInterface *self) * within the stats structure may be returned as -1, which indicates * that the hypervisor does not support that particular statistic. * - * Returns: (transfer full): the stats or %NULL in case of error + * Returns: (transfer full): the stats or %NULL in case of error. The + * returned object should be unreffed with g_object_unref() when no longer + * needed. **/ GVirDomainInterfaceStats *gvir_domain_interface_get_stats(GVirDomainInterface *self, GError **err) { diff --git a/libvirt-gobject/libvirt-gobject-domain-snapshot.c b/libvirt-gobject/libvirt-gobject-domain-snapshot.c index dbf0c51..d06d4d5 100644 --- a/libvirt-gobject/libvirt-gobject-domain-snapshot.c +++ b/libvirt-gobject/libvirt-gobject-domain-snapshot.c @@ -185,7 +185,9 @@ const gchar *gvir_domain_snapshot_get_name(GVirDomainSnapshot *snapshot) * @snapshot: the domain_snapshot * @flags: the flags * - * Returns: (transfer full): the config + * Returns: (transfer full): the config. The returned object should be + * unreffed with g_object_unref() when no longer needed. + */ GVirConfigDomainSnapshot *gvir_domain_snapshot_get_config (GVirDomainSnapshot *snapshot, diff --git a/libvirt-gobject/libvirt-gobject-domain.c b/libvirt-gobject/libvirt-gobject-domain.c index e5113d4..9be568a 100644 --- a/libvirt-gobject/libvirt-gobject-domain.c +++ b/libvirt-gobject/libvirt-gobject-domain.c @@ -455,7 +455,8 @@ gboolean gvir_domain_reboot(GVirDomain *dom, * @dom: the domain * @flags: the flags * - * Returns: (transfer full): the config + * Returns: (transfer full): the config. The returned object should be + * unreffed with g_object_unref() when no longer needed. */ GVirConfigDomain *gvir_domain_get_config(GVirDomain *dom, guint flags, @@ -549,7 +550,8 @@ gboolean gvir_domain_set_config(GVirDomain *domain, * gvir_domain_get_info: * @dom: the domain * - * Returns: (transfer full): the info + * Returns: (transfer full): the info. The returned object should be + * unreffed with g_object_unref() when no longer needed. */ GVirDomainInfo *gvir_domain_get_info(GVirDomain *dom, GError **err) @@ -631,7 +633,8 @@ void gvir_domain_get_info_async(GVirDomain *dom, * * Finishes the operation started by #gvir_domain_get_info_async. * - * Returns: (transfer full): the info + * Returns: (transfer full): the info. The returned object should be + * unreffed with g_object_unref() when no longer needed. */ GVirDomainInfo *gvir_domain_get_info_finish(GVirDomain *dom, GAsyncResult *result, @@ -661,7 +664,8 @@ GVirDomainInfo *gvir_domain_get_info_finish(GVirDomain *dom, * @monitor_id: monitor ID to take screenshot from * @flags: extra flags, currently unused * - * Returns: (transfer full): mime-type of the image format, or NULL upon error. + * Returns: (transfer full): a newly allocated string containing the + * mime-type of the image format, or NULL upon error. */ gchar *gvir_domain_screenshot(GVirDomain *dom, GVirStream *stream, @@ -958,7 +962,9 @@ gboolean gvir_domain_get_saved(GVirDomain *dom) * @domain: the domain * @err: place-holder for possible errors, or NULL * - * Gets the list of devices attached to @domain + * Gets the list of devices attached to @domain. The returned list should + * be freed with g_list_free(), after its elements have been unreffed with + * g_object_unref(). * * Returns: (element-type LibvirtGObject.DomainDevice) (transfer full): a newly * allocated #GList of #GVirDomainDevice. diff --git a/libvirt-gobject/libvirt-gobject-interface.c b/libvirt-gobject/libvirt-gobject-interface.c index a8e299c..883cf92 100644 --- a/libvirt-gobject/libvirt-gobject-interface.c +++ b/libvirt-gobject/libvirt-gobject-interface.c @@ -177,7 +177,8 @@ const gchar *gvir_interface_get_name(GVirInterface *iface) * @flags: the flags * @err: Place-holder for possible errors * - * Returns: (transfer full): the config + * Returns: (transfer full): the config. The returned object should be + * unreffed with g_object_unref() when no longer needed. */ GVirConfigInterface *gvir_interface_get_config(GVirInterface *iface, guint flags, diff --git a/libvirt-gobject/libvirt-gobject-manager.c b/libvirt-gobject/libvirt-gobject-manager.c index 010e8da..c44e711 100644 --- a/libvirt-gobject/libvirt-gobject-manager.c +++ b/libvirt-gobject/libvirt-gobject-manager.c @@ -161,7 +161,9 @@ void gvir_manager_remove_connection(GVirManager *man, /** * gvir_manager_get_connections: * - * Returns: (transfer full)(element-type GVirConnection): the connections + * Returns: (transfer full)(element-type GVirConnection): the connections. + * The returned list should be freed with g_list_free(), after its elements + * have been unreffed with g_object_unref(). */ GList *gvir_manager_get_connections(GVirManager *man) { @@ -181,7 +183,9 @@ GList *gvir_manager_get_connections(GVirManager *man) /** * gvir_manager_find_connection_by_uri: * - * Returns: (transfer full)(allow-none): the connection,or NULL + * Returns: (transfer full)(allow-none): the connection,or NULL. The + * returned object should be unreffed with g_object_unref() when no longer + * needed. */ GVirConnection *gvir_manager_find_connection_by_uri(GVirManager *man, const gchar *uri) diff --git a/libvirt-gobject/libvirt-gobject-network-filter.c b/libvirt-gobject/libvirt-gobject-network-filter.c index 103174b..b3db236 100644 --- a/libvirt-gobject/libvirt-gobject-network-filter.c +++ b/libvirt-gobject/libvirt-gobject-network-filter.c @@ -208,7 +208,9 @@ const gchar *gvir_network_filter_get_uuid(GVirNetworkFilter *filter) * @flags: the flags * @err: Place-holder for possible errors * - * Returns: (transfer full): the config + * Returns: (transfer full): the config. The returned object should be + * unreffed with g_object_unref() when no longer needed. + */ GVirConfigNetworkFilter *gvir_network_filter_get_config (GVirNetworkFilter *filter, diff --git a/libvirt-gobject/libvirt-gobject-network.c b/libvirt-gobject/libvirt-gobject-network.c index 2d195d9..17378ec 100644 --- a/libvirt-gobject/libvirt-gobject-network.c +++ b/libvirt-gobject/libvirt-gobject-network.c @@ -205,7 +205,8 @@ const gchar *gvir_network_get_uuid(GVirNetwork *network) * @flags: the flags * @err: Place-holder for possible errors * - * Returns: (transfer full): the config + * Returns: (transfer full): the config. The returned object should be + * unreffed with g_object_unref() when no longer needed. */ GVirConfigNetwork *gvir_network_get_config(GVirNetwork *network, guint flags, diff --git a/libvirt-gobject/libvirt-gobject-node-device.c b/libvirt-gobject/libvirt-gobject-node-device.c index 6f81f1a..0a4b6a6 100644 --- a/libvirt-gobject/libvirt-gobject-node-device.c +++ b/libvirt-gobject/libvirt-gobject-node-device.c @@ -177,7 +177,9 @@ const gchar *gvir_node_device_get_name(GVirNodeDevice *device) * @flags: the flags * @err: Place-holder for possible errors * - * Returns: (transfer full): the config + * Returns: (transfer full): the config. The returned object should be + * unreffed with g_object_unref() when no longer needed. + */ GVirConfigNodeDevice *gvir_node_device_get_config(GVirNodeDevice *device, guint flags, diff --git a/libvirt-gobject/libvirt-gobject-secret.c b/libvirt-gobject/libvirt-gobject-secret.c index 299fdca..b0aff13 100644 --- a/libvirt-gobject/libvirt-gobject-secret.c +++ b/libvirt-gobject/libvirt-gobject-secret.c @@ -193,7 +193,9 @@ const gchar *gvir_secret_get_uuid(GVirSecret *secret) * @flags: the flags * @err: Place-holder for possible errors * - * Returns: (transfer full): the config + * Returns: (transfer full): the config. The returned object should be + * unreffed with g_object_unref() when no longer needed. + */ GVirConfigSecret *gvir_secret_get_config(GVirSecret *secret, guint flags, diff --git a/libvirt-gobject/libvirt-gobject-storage-pool.c b/libvirt-gobject/libvirt-gobject-storage-pool.c index f09f122..e79c8e5 100644 --- a/libvirt-gobject/libvirt-gobject-storage-pool.c +++ b/libvirt-gobject/libvirt-gobject-storage-pool.c @@ -237,7 +237,8 @@ const gchar *gvir_storage_pool_get_uuid(GVirStoragePool *pool) * @flags: the flags * @err: Place-holder for possible errors * - * Returns: (transfer full): the config + * Returns: (transfer full): the config. The returned object should be + * unreffed with g_object_unref() when no longer needed. */ GVirConfigStoragePool *gvir_storage_pool_get_config(GVirStoragePool *pool, guint flags, @@ -264,7 +265,8 @@ GVirConfigStoragePool *gvir_storage_pool_get_config(GVirStoragePool *pool, * @pool: the storage_pool * @err: Place-holder for possible errors * - * Returns: (transfer full): the info + * Returns: (transfer full): the info. The returned object should be + * unreffed with g_object_unref() when no longer needed. */ GVirStoragePoolInfo *gvir_storage_pool_get_info(GVirStoragePool *pool, GError **err) @@ -486,8 +488,10 @@ static void gvir_storage_vol_ref(gpointer obj, gpointer ignore G_GNUC_UNUSED) * gvir_storage_pool_get_volumes: * @pool: the storage pool * - * Return value: (element-type LibvirtGObject.StorageVol) (transfer full): List - * of #GVirStorageVol + * Return value: (element-type LibvirtGObject.StorageVol) (transfer full): + * List of #GVirStorageVol. The returned list should be freed with + * g_list_free(), after its elements have been unreffed with + * g_object_unref(). */ GList *gvir_storage_pool_get_volumes(GVirStoragePool *pool) { @@ -509,7 +513,9 @@ GList *gvir_storage_pool_get_volumes(GVirStoragePool *pool) * @pool: the storage pool * @name: Name of the requested storage volume * - * Return value: (transfer full): the #GVirStorageVol, or NULL + * Return value: (transfer full): the #GVirStorageVol, or NULL. The + * returned object should be unreffed with g_object_unref() when no longer + * needed. */ GVirStorageVol *gvir_storage_pool_get_volume(GVirStoragePool *pool, const gchar *name) @@ -532,7 +538,8 @@ GVirStorageVol *gvir_storage_pool_get_volume(GVirStoragePool *pool, * @conf: the configuration for the new volume * @err: Place-holder for possible errors * - * Returns: (transfer full): the newly created volume + * Returns: (transfer full): the newly created volume. The returned object + * should be unreffed with g_object_unref() when no longer needed. */ GVirStorageVol *gvir_storage_pool_create_volume (GVirStoragePool *pool, diff --git a/libvirt-gobject/libvirt-gobject-storage-vol.c b/libvirt-gobject/libvirt-gobject-storage-vol.c index cd02b38..9e59576 100644 --- a/libvirt-gobject/libvirt-gobject-storage-vol.c +++ b/libvirt-gobject/libvirt-gobject-storage-vol.c @@ -227,7 +227,8 @@ const gchar *gvir_storage_vol_get_path(GVirStorageVol *vol, GError **error) * @flags: the flags * @err: Place-holder for possible errors * - * Returns: (transfer full): the config + * Returns: (transfer full): the config. The returned object should be + * unreffed with g_object_unref() when no longer needed. */ GVirConfigStorageVol *gvir_storage_vol_get_config(GVirStorageVol *vol, guint flags, @@ -254,7 +255,8 @@ GVirConfigStorageVol *gvir_storage_vol_get_config(GVirStorageVol *vol, * @vol: the storage_vol * @err: Place-holder for possible errors * - * Returns: (transfer full): the info + * Returns: (transfer full): the info. The returned object should be + * unreffed with g_object_unref() when no longer needed. */ GVirStorageVolInfo *gvir_storage_vol_get_info(GVirStorageVol *vol, GError **err) -- 1.7.10.1