docs: improve event-related documentation

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@redhat.com>

diff --git a/include/libvirt/libvirt.h.in b/include/libvirt/libvirt.h.in
index aa042b472975a98ae3dae4dcf7217a8809f68979..018a5ce49077f90af044263227ddab83c42e02b0 100644 (file)
--- a/include/libvirt/libvirt.h.in
+++ b/include/libvirt/libvirt.h.in
@@ -4508,14 +4508,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,
@@ -4930,11 +4933,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 */
@@ -5015,10 +5025,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 */
 
@@ -5032,14 +5049,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 d15d6179cb0f60fe151f29d43cb4c5c22bec4f73..77f481ebf9e761887455ba1076c33a9eb388d973 100644 (file)
--- 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
  */