datatypes: Fix comments

- As of commit 2ff4c137, all virGet*() functions in datatypes.c always
  return pointers to new objects. Objects are not cached in a
  per-connection hashtable.

- Fix variable names in comments for all vir*Dispose() functions in
  datatypes.c.

- Add comments for virGetStream(), virStreamDispose(),
  virGetDomainSnapshot(), virDomainSnapshotDispose().

Signed-off-by: Michael Chapman <mike@very.puzzling.org>

src/datatypes.c

@@ -96,9 +96,9 @@ VIR_ONCE_GLOBAL_INIT(virDataTypes)
 /**
  * virGetConnect:
  *
- * Allocates a new hypervisor connection structure
+ * Allocates a new hypervisor connection object.
  *
- * Returns a new pointer or NULL in case of error.
+ * Returns a pointer to the connection object, or NULL on error.
  */
 virConnectPtr
 virGetConnect(void)
@@ -126,7 +126,7 @@ error:
 
 /**
  * virConnectDispose:
- * @conn: the hypervisor connection to release
+ * @obj: the hypervisor connection to release
  *
  * Unconditionally release all memory associated with a connection.
  * The connection object must not be used once this method returns.
@@ -196,12 +196,10 @@ virConnectCloseCallbackDataDispose(void *obj)
  * @name: pointer to the domain name
  * @uuid: pointer to the uuid
  *
- * Lookup if the domain is already registered for that connection,
+ * Allocates a new domain object. When the object is no longer needed,
- * if yes return a new pointer to it, if no allocate a new structure,
+ * virObjectUnref() must be called in order to not leak data.
- * and register it in the table. In any case a corresponding call to
- * virObjectUnref() is needed to not leak data.
  *
- * Returns a pointer to the domain, or NULL in case of failure
+ * Returns a pointer to the domain object, or NULL on error.
  */
 virDomainPtr
 virGetDomain(virConnectPtr conn, const char *name, const unsigned char *uuid)
@@ -234,7 +232,7 @@ error:
 
 /**
  * virDomainDispose:
- * @domain: the domain to release
+ * @obj: the domain to release
  *
  * Unconditionally release all memory associated with a domain.
  * The domain object must not be used once this method returns.
@@ -262,12 +260,10 @@ virDomainDispose(void *obj)
  * @name: pointer to the network name
  * @uuid: pointer to the uuid
  *
- * Lookup if the network is already registered for that connection,
+ * Allocates a new network object. When the object is no longer needed,
- * if yes return a new pointer to it, if no allocate a new structure,
+ * virObjectUnref() must be called in order to not leak data.
- * and register it in the table. In any case a corresponding call to
- * virObjectUnref() is needed to not leak data.
  *
- * Returns a pointer to the network, or NULL in case of failure
+ * Returns a pointer to the network object, or NULL on error.
  */
 virNetworkPtr
 virGetNetwork(virConnectPtr conn, const char *name, const unsigned char *uuid)
@@ -299,7 +295,7 @@ error:
 
 /**
  * virNetworkDispose:
- * @network: the network to release
+ * @obj: the network to release
  *
  * Unconditionally release all memory associated with a network.
  * The network object must not be used once this method returns.
@@ -327,13 +323,10 @@ virNetworkDispose(void *obj)
  * @name: pointer to the interface name
  * @mac: pointer to the mac
  *
- * Lookup if the interface is already registered for that connection,
+ * Allocates a new interface object. When the object is no longer needed,
- * if yes return a new pointer to it (possibly updating the MAC
+ * virObjectUnref() must be called in order to not leak data.
- * address), if no allocate a new structure, and register it in the
- * table. In any case a corresponding call to virObjectUnref() is
- * needed to not leak data.
  *
- * Returns a pointer to the interface, or NULL in case of failure
+ * Returns a pointer to the interface object, or NULL on error.
  */
 virInterfacePtr
 virGetInterface(virConnectPtr conn, const char *name, const char *mac)
@@ -368,7 +361,7 @@ error:
 
 /**
  * virInterfaceDispose:
- * @interface: the interface to release
+ * @obj: the interface to release
  *
  * Unconditionally release all memory associated with an interface.
  * The interface object must not be used once this method returns.
@@ -396,12 +389,10 @@ virInterfaceDispose(void *obj)
  * @privateData: pointer to driver specific private data
  * @freeFunc: private data cleanup function pointer specfic to driver
  *
- * Lookup if the storage pool is already registered for that connection,
+ * Allocates a new storage pool object. When the object is no longer needed,
- * if yes return a new pointer to it, if no allocate a new structure,
+ * virObjectUnref() must be called in order to not leak data.
- * and register it in the table. In any case a corresponding call to
- * virObjectUnref() is needed to not leak data.
  *
- * Returns a pointer to the storage pool, or NULL in case of failure
+ * Returns a pointer to the storage pool object, or NULL on error.
  */
 virStoragePoolPtr
 virGetStoragePool(virConnectPtr conn, const char *name,
@@ -440,7 +431,7 @@ error:
 
 /**
  * virStoragePoolDispose:
- * @pool: the pool to release
+ * @obj: the storage pool to release
  *
  * Unconditionally release all memory associated with a pool.
  * The pool object must not be used once this method returns.
@@ -475,12 +466,10 @@ virStoragePoolDispose(void *obj)
  * @privateData: pointer to driver specific private data
  * @freeFunc: private data cleanup function pointer specfic to driver
  *
- * Lookup if the storage vol is already registered for that connection,
+ * Allocates a new storage volume object. When the object is no longer needed,
- * if yes return a new pointer to it, if no allocate a new structure,
+ * virObjectUnref() must be called in order to not leak data.
- * and register it in the table. In any case a corresponding call to
- * virObjectUnref() is needed to not leak data.
  *
- * Returns a pointer to the storage vol, or NULL in case of failure
+ * Returns a pointer to the storage volume object, or NULL on error.
  */
 virStorageVolPtr
 virGetStorageVol(virConnectPtr conn, const char *pool, const char *name,
@@ -520,7 +509,7 @@ error:
 
 /**
  * virStorageVolDispose:
- * @vol: the vol to release
+ * @obj: the storage volume to release
  *
  * Unconditionally release all memory associated with a volume.
  * The volume object must not be used once this method returns.
@@ -550,12 +539,10 @@ virStorageVolDispose(void *obj)
  * @conn: the hypervisor connection
  * @name: device name (unique on node)
  *
- * Lookup if the device is already registered for that connection,
+ * Allocates a new node device object. When the object is no longer needed,
- * if yes return a new pointer to it, if no allocate a new structure,
+ * virObjectUnref() must be called in order to not leak data.
- * and register it in the table. In any case a corresponding call to
- * virObjectUnref() is needed to not leak data.
  *
- * Returns a pointer to the node device, or NULL in case of failure
+ * Returns a pointer to the node device object, or NULL on error.
  */
 virNodeDevicePtr
 virGetNodeDevice(virConnectPtr conn, const char *name)
@@ -585,7 +572,7 @@ error:
 
 /**
  * virNodeDeviceDispose:
- * @dev: the dev to release
+ * @obj: the node device to release
  *
  * Unconditionally release all memory associated with a device.
  * The device object must not be used once this method returns.
@@ -611,12 +598,10 @@ virNodeDeviceDispose(void *obj)
  * @conn: the hypervisor connection
  * @uuid: secret UUID
  *
- * Lookup if the secret is already registered for that connection, if so return
+ * Allocates a new secret object. When the object is no longer needed,
- * a pointer to it, otherwise allocate a new structure, and register it in the
+ * virObjectUnref() must be called in order to not leak data.
- * table. In any case a corresponding call to virObjectUnref() is needed to not
- * leak data.
  *
- * Returns a pointer to the secret, or NULL in case of failure
+ * Returns a pointer to the secret object, or NULL on error.
  */
 virSecretPtr
 virGetSecret(virConnectPtr conn, const unsigned char *uuid,
@@ -650,7 +635,7 @@ error:
 
 /**
  * virSecretDispose:
- * @secret: the secret to release
+ * @obj: the secret to release
  *
  * Unconditionally release all memory associated with a secret.
  * The secret object must not be used once this method returns.
@@ -672,6 +657,15 @@ virSecretDispose(void *obj)
 }
 
 
+/**
+ * virGetStream:
+ * @conn: the hypervisor connection
+ *
+ * Allocates a new stream object. When the object is no longer needed,
+ * virObjectUnref() must be called in order to not leak data.
+ *
+ * Returns a pointer to the stream object, or NULL on error.
+ */
 virStreamPtr
 virGetStream(virConnectPtr conn)
 {
@@ -688,6 +682,16 @@ virGetStream(virConnectPtr conn)
     return ret;
 }
 
+/**
+ * virStreamDispose:
+ * @obj: the stream to release
+ *
+ * Unconditionally release all memory associated with a stream.
+ * The stream object must not be used once this method returns.
+ *
+ * It will also unreference the associated connection object,
+ * which may also be released if its ref count hits zero.
+ */
 static void
 virStreamDispose(void *obj)
 {
@@ -704,12 +708,10 @@ virStreamDispose(void *obj)
  * @name: pointer to the network filter pool name
  * @uuid: pointer to the uuid
  *
- * Lookup if the network filter is already registered for that connection,
+ * Allocates a new network filter object. When the object is no longer needed,
- * if yes return a new pointer to it, if no allocate a new structure,
+ * virObjectUnref() must be called in order to not leak data.
- * and register it in the table. In any case a corresponding call to
- * virObjectUnref() is needed to not leak data.
  *
- * Returns a pointer to the network, or NULL in case of failure
+ * Returns a pointer to the network filter object, or NULL on error.
  */
 virNWFilterPtr
 virGetNWFilter(virConnectPtr conn, const char *name,
@@ -744,7 +746,7 @@ error:
 
 /**
  * virNWFilterDispose:
- * @nwfilter: the nwfilter to release
+ * @obj: the network filter to release
  *
  * Unconditionally release all memory associated with a nwfilter.
  * The nwfilter object must not be used once this method returns.
@@ -766,6 +768,16 @@ virNWFilterDispose(void *obj)
 }
 
 
+/**
+ * virGetDomainSnapshot:
+ * @domain: the domain to snapshot
+ * @name: pointer to the domain snapshot name
+ *
+ * Allocates a new domain snapshot object. When the object is no longer needed,
+ * virObjectUnref() must be called in order to not leak data.
+ *
+ * Returns a pointer to the domain snapshot object, or NULL on error.
+ */
 virDomainSnapshotPtr
 virGetDomainSnapshot(virDomainPtr domain, const char *name)
 {
@@ -792,6 +804,16 @@ error:
 }
 
 
+/**
+ * virDomainSnapshotDispose:
+ * @obj: the domain snapshot to release
+ *
+ * Unconditionally release all memory associated with a snapshot.
+ * The snapshot object must not be used once this method returns.
+ *
+ * It will also unreference the associated connection object,
+ * which may also be released if its ref count hits zero.
+ */
 static void
 virDomainSnapshotDispose(void *obj)
 {