10:37 a.m.
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