From 3e67714e480ca2a6483fca4e31acea05f8532068 Mon Sep 17 00:00:00 2001 From: Eric Blake Date: Thu, 19 Dec 2013 05:49:35 -0700 Subject: [PATCH] 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 --- 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 aa042b4729..018a5ce490 100644 --- 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 d15d6179cb..77f481ebf9 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 */