[libvirt] [libvirt-glib] Make memory-handling more explicit in API doc

Christophe Fergeau cfergeau at redhat.com
Fri May 11 15:37:37 UTC 2012


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




More information about the libvir-list mailing list