[libvirt] [PATCH 1/2] docs: improve event-related documentation
Eric Blake
eblake at redhat.com
Thu Dec 19 15:13:35 UTC 2013
While looking at event code, I noticed that the documentation was
trying to refer me to functions that don't exist. Also fix some
typos and poor formatting.
* src/libvirt.c (virConnectDomainEventDeregister)
(virConnectDomainEventRegisterAny)
(virConnectDomainEventDeregisterAny)
(virConnectNetworkEventRegisterAny)
(virConnectNetworkEventDeregisterAny): Link to correct function.
* include/libvirt.h.in (VIR_DOMAIN_EVENT_CALLBACK)
(VIR_NETWORK_EVENT_CALLBACK): Likewise.
(virDomainEventID, virConnectDomainEventGenericCallback)
(virNetworkEventID, virConnectNetworkEventGenericCallback):
Improve docs.
Signed-off-by: Eric Blake <eblake at redhat.com>
---
include/libvirt/libvirt.h.in | 36 ++++++++++++++++++++++++++++--------
src/libvirt.c | 24 ++++++++++++------------
2 files changed, 40 insertions(+), 20 deletions(-)
diff --git a/include/libvirt/libvirt.h.in b/include/libvirt/libvirt.h.in
index 6f79c49..b6c4cd0 100644
--- a/include/libvirt/libvirt.h.in
+++ b/include/libvirt/libvirt.h.in
@@ -4507,14 +4507,17 @@ int virDomainSnapshotDelete(virDomainSnapshotPtr snapshot,
int virDomainSnapshotRef(virDomainSnapshotPtr snapshot);
int virDomainSnapshotFree(virDomainSnapshotPtr snapshot);
-/*
+/**
* virConnectDomainEventGenericCallback:
* @conn: the connection pointer
* @dom: the domain pointer
* @opaque: application specified data
*
- * A generic domain event callback handler. Specific events usually
- * have a customization with extra parameters
+ * A generic domain event callback handler, for use with
+ * virConnectDomainEventRegisterAny(). Specific events usually
+ * have a customization with extra parameters, often with @opaque being
+ * passed in a different parameter position; use VIR_DOMAIN_EVENT_CALLBACK()
+ * when registering an appropriate handler.
*/
typedef void (*virConnectDomainEventGenericCallback)(virConnectPtr conn,
virDomainPtr dom,
@@ -4929,11 +4932,18 @@ typedef void (*virConnectDomainEventDeviceRemovedCallback)(virConnectPtr conn,
* VIR_DOMAIN_EVENT_CALLBACK:
*
* Used to cast the event specific callback into the generic one
- * for use for virDomainEventRegister
+ * for use for virConnectDomainEventRegisterAny()
*/
#define VIR_DOMAIN_EVENT_CALLBACK(cb) ((virConnectDomainEventGenericCallback)(cb))
+/**
+ * virDomainEventID:
+ *
+ * An enumeration of supported eventId parameters for
+ * virConnectDomainEventRegisterAny(). Each event id determines which
+ * signature of callback function will be used.
+ */
typedef enum {
VIR_DOMAIN_EVENT_ID_LIFECYCLE = 0, /* virConnectDomainEventCallback */
VIR_DOMAIN_EVENT_ID_REBOOT = 1, /* virConnectDomainEventGenericCallback */
@@ -5014,10 +5024,17 @@ typedef void (*virConnectNetworkEventLifecycleCallback)(virConnectPtr conn,
* VIR_NETWORK_EVENT_CALLBACK:
*
* Used to cast the event specific callback into the generic one
- * for use for virNetworkEventRegister
+ * for use for virConnectNetworkEventRegisterAny()
*/
#define VIR_NETWORK_EVENT_CALLBACK(cb) ((virConnectNetworkEventGenericCallback)(cb))
+/**
+ * virNetworkEventID:
+ *
+ * An enumeration of supported eventId parameters for
+ * virConnectNetworkEventRegisterAny(). Each event id determines which
+ * signature of callback function will be used.
+ */
typedef enum {
VIR_NETWORK_EVENT_ID_LIFECYCLE = 0, /* virConnectNetworkEventLifecycleCallback */
@@ -5031,14 +5048,17 @@ typedef enum {
#endif
} virNetworkEventID;
-/*
+/**
* virConnectNetworkEventGenericCallback:
* @conn: the connection pointer
* @net: the network pointer
* @opaque: application specified data
*
- * A generic network event callback handler. Specific events usually
- * have a customization with extra parameters
+ * A generic network event callback handler, for use with
+ * virConnectNetworkEventRegisterAny(). Specific events usually
+ * have a customization with extra parameters, often with @opaque being
+ * passed in a different parameter position; use VIR_NETWORK_EVENT_CALLBACK()
+ * when registering an appropriate handler.
*/
typedef void (*virConnectNetworkEventGenericCallback)(virConnectPtr conn,
virNetworkPtr net,
diff --git a/src/libvirt.c b/src/libvirt.c
index d15d617..77f481e 100644
--- a/src/libvirt.c
+++ b/src/libvirt.c
@@ -16127,7 +16127,7 @@ error:
* occurring on a connection
*
* Use of this method is no longer recommended. Instead applications
- * should try virConnectDomainEventRegisterAny which has a more flexible
+ * should try virConnectDomainEventRegisterAny() which has a more flexible
* API contract
*
* The virDomainPtr object handle passed into the callback upon delivery
@@ -16178,7 +16178,7 @@ error:
* function.
*
* Use of this method is no longer recommended. Instead applications
- * should try virConnectDomainEventUnregisterAny which has a more flexible
+ * should try virConnectDomainEventDeregisterAny() which has a more flexible
* API contract
*
* Returns 0 on success, -1 on failure
@@ -19069,7 +19069,7 @@ error:
* Adds a callback to receive notifications of arbitrary domain events
* occurring on a domain.
*
- * If dom is NULL, then events will be monitored for any domain. If dom
+ * If @dom is NULL, then events will be monitored for any domain. If @dom
* is non-NULL, then only the specific domain will be monitored
*
* Most types of event have a callback providing a custom set of parameters
@@ -19080,13 +19080,13 @@ error:
* The virDomainPtr object handle passed into the callback upon delivery
* of an event is only valid for the duration of execution of the callback.
* If the callback wishes to keep the domain object after the callback returns,
- * it shall take a reference to it, by calling virDomainRef.
+ * it shall take a reference to it, by calling virDomainRef().
* The reference can be released once the object is no longer required
- * by calling virDomainFree.
+ * by calling virDomainFree().
*
* The return value from this method is a positive integer identifier
* for the callback. To unregister a callback, this callback ID should
- * be passed to the virDomainEventUnregisterAny method
+ * be passed to the virConnectDomainEventDeregisterAny() method.
*
* Returns a callback identifier on success, -1 on failure
*/
@@ -19143,7 +19143,7 @@ error:
* @callbackID: the callback identifier
*
* Removes an event callback. The callbackID parameter should be the
- * vaule obtained from a previous virDomainEventRegisterAny method.
+ * value obtained from a previous virConnectDomainEventRegisterAny() method.
*
* Returns 0 on success, -1 on failure
*/
@@ -19188,7 +19188,7 @@ error:
* Adds a callback to receive notifications of arbitrary network events
* occurring on a network.
*
- * If net is NULL, then events will be monitored for any network. If net
+ * If @net is NULL, then events will be monitored for any network. If @net
* is non-NULL, then only the specific network will be monitored
*
* Most types of event have a callback providing a custom set of parameters
@@ -19199,13 +19199,13 @@ error:
* The virNetworkPtr object handle passed into the callback upon delivery
* of an event is only valid for the duration of execution of the callback.
* If the callback wishes to keep the network object after the callback
- * returns, it shall take a reference to it, by calling virNetworkRef.
+ * returns, it shall take a reference to it, by calling virNetworkRef().
* The reference can be released once the object is no longer required
- * by calling virNetworkFree.
+ * by calling virNetworkFree().
*
* The return value from this method is a positive integer identifier
* for the callback. To unregister a callback, this callback ID should
- * be passed to the virNetworkEventUnregisterAny method
+ * be passed to the virConnectNetworkEventDeregisterAny() method.
*
* Returns a callback identifier on success, -1 on failure
*/
@@ -19266,7 +19266,7 @@ error:
* @callbackID: the callback identifier
*
* Removes an event callback. The callbackID parameter should be the
- * vaule obtained from a previous virNetworkEventRegisterAny method.
+ * value obtained from a previous virConnectNetworkEventRegisterAny() method.
*
* Returns 0 on success, -1 on failure
*/
--
1.8.4.2
More information about the libvir-list
mailing list