event: fix doc typos, and doc more public methods

While working on events, I found a number of minor issues; I'm
hoisting these to the front rather than doing it piecemeal in
the patches where I first noticed bad or missing documentation.

* src/conf/object_event.c: Fix grammar, document all parameters
of public functions, wrap some long lines.
* src/conf/object_event.h: Likewise.
* src/conf/network_event.c: Likewise.
* src/conf/domain_event.c: Likewise (except for the large number
of event creation functions).
* src/libvirt_private.cyms (conf/object_event.h): Split...
(conf/network_event.h): ...to account for new file.

Signed-off-by: Eric Blake <eblake@redhat.com>

src/conf/domain_event.c

@@ -1,7 +1,7 @@
 /*
  * domain_event.c: domain event queue processing helpers
  *
- * Copyright (C) 2010-2013 Red Hat, Inc.
+ * Copyright (C) 2010-2014 Red Hat, Inc.
  * Copyright (C) 2008 VirtualIron
  * Copyright (C) 2013 SUSE LINUX Products GmbH, Nuernberg, Germany.
  *
@@ -70,7 +70,7 @@ virDomainEventDispatchDefaultFunc(virConnectPtr conn,
 struct _virDomainEvent {
     virObjectEvent parent;
 
-    /* Unused attribute to get virDomainEvent class being created */
+    /* Unused attribute to allow for subclass creation */
     bool dummy;
 };
 typedef struct _virDomainEvent virDomainEvent;
@@ -172,7 +172,8 @@ typedef struct _virDomainEventDeviceRemoved virDomainEventDeviceRemoved;
 typedef virDomainEventDeviceRemoved *virDomainEventDeviceRemovedPtr;
 
 
-static int virDomainEventsOnceInit(void)
+static int
+virDomainEventsOnceInit(void)
 {
     if (!(virDomainEventClass =
           virClassNew(virClassForObjectEvent(),
@@ -246,32 +247,37 @@ static int virDomainEventsOnceInit(void)
 VIR_ONCE_GLOBAL_INIT(virDomainEvents)
 
 
-static void virDomainEventDispose(void *obj)
+static void
+virDomainEventDispose(void *obj)
 {
     virDomainEventPtr event = obj;
 
     VIR_DEBUG("obj=%p", event);
 }
 
-static void virDomainEventLifecycleDispose(void *obj)
+static void
+virDomainEventLifecycleDispose(void *obj)
 {
     virDomainEventLifecyclePtr event = obj;
     VIR_DEBUG("obj=%p", event);
 }
 
-static void virDomainEventRTCChangeDispose(void *obj)
+static void
+virDomainEventRTCChangeDispose(void *obj)
 {
     virDomainEventRTCChangePtr event = obj;
     VIR_DEBUG("obj=%p", event);
 }
 
-static void virDomainEventWatchdogDispose(void *obj)
+static void
+virDomainEventWatchdogDispose(void *obj)
 {
     virDomainEventWatchdogPtr event = obj;
     VIR_DEBUG("obj=%p", event);
 }
 
-static void virDomainEventIOErrorDispose(void *obj)
+static void
+virDomainEventIOErrorDispose(void *obj)
 {
     virDomainEventIOErrorPtr event = obj;
     VIR_DEBUG("obj=%p", event);
@@ -281,7 +287,8 @@ static void virDomainEventIOErrorDispose(void *obj)
     VIR_FREE(event->reason);
 }
 
-static void virDomainEventGraphicsDispose(void *obj)
+static void
+virDomainEventGraphicsDispose(void *obj)
 {
     virDomainEventGraphicsPtr event = obj;
     VIR_DEBUG("obj=%p", event);
@@ -307,7 +314,8 @@ static void virDomainEventGraphicsDispose(void *obj)
     }
 }
 
-static void virDomainEventBlockJobDispose(void *obj)
+static void
+virDomainEventBlockJobDispose(void *obj)
 {
     virDomainEventBlockJobPtr event = obj;
     VIR_DEBUG("obj=%p", event);
@@ -315,7 +323,8 @@ static void virDomainEventBlockJobDispose(void *obj)
     VIR_FREE(event->path);
 }
 
-static void virDomainEventDiskChangeDispose(void *obj)
+static void
+virDomainEventDiskChangeDispose(void *obj)
 {
     virDomainEventDiskChangePtr event = obj;
     VIR_DEBUG("obj=%p", event);
@@ -325,7 +334,8 @@ static void virDomainEventDiskChangeDispose(void *obj)
     VIR_FREE(event->devAlias);
 }
 
-static void virDomainEventTrayChangeDispose(void *obj)
+static void
+virDomainEventTrayChangeDispose(void *obj)
 {
     virDomainEventTrayChangePtr event = obj;
     VIR_DEBUG("obj=%p", event);
@@ -333,13 +343,15 @@ static void virDomainEventTrayChangeDispose(void *obj)
     VIR_FREE(event->devAlias);
 }
 
-static void virDomainEventBalloonChangeDispose(void *obj)
+static void
+virDomainEventBalloonChangeDispose(void *obj)
 {
     virDomainEventBalloonChangePtr event = obj;
     VIR_DEBUG("obj=%p", event);
 }
 
-static void virDomainEventDeviceRemovedDispose(void *obj)
+static void
+virDomainEventDeviceRemovedDispose(void *obj)
 {
     virDomainEventDeviceRemovedPtr event = obj;
     VIR_DEBUG("obj=%p", event);
@@ -354,7 +366,9 @@ static void virDomainEventDeviceRemovedDispose(void *obj)
  * @cbList: the list
  * @callback: the callback to remove
  *
- * Internal function to remove a callback from a virObjectEventCallbackListPtr
+ * Internal function to remove a callback from a virObjectEventCallbackListPtr,
+ * when registered via the older virConnectDomainEventRegister with no
+ * callbackID
  */
 static int
 virDomainEventCallbackListRemove(virConnectPtr conn,
@@ -430,9 +444,11 @@ virDomainEventCallbackListMarkDelete(virConnectPtr conn,
  * @conn: pointer to the connection
  * @cbList: the list
  * @callback: the callback to add
- * @opaque: opaque data tio pass to callback
+ * @opaque: opaque data to pass to @callback
+ * @freecb: callback to free @opaque
  *
- * Internal function to add a callback from a virObjectEventCallbackListPtr
+ * Internal function to add a callback from a virObjectEventCallbackListPtr,
+ * when registered via the older virConnectDomainEventRegister.
  */
 static int
 virDomainEventCallbackListAdd(virConnectPtr conn,
@@ -1355,8 +1371,8 @@ cleanup:
  * virDomainEventStateRegister:
  * @conn: connection to associate with callback
  * @state: object event state
- * @callback: function to remove from event
+ * @callback: the callback to add
- * @opaque: data blob to pass to callback
+ * @opaque: data blob to pass to @callback
  * @freecb: callback to free @opaque
  *
  * Register the function @callback with connection @conn,
@@ -1409,14 +1425,16 @@ cleanup:
  * virDomainEventStateRegisterID:
  * @conn: connection to associate with callback
  * @state: object event state
+ * @dom: optional domain for filtering the event
  * @eventID: ID of the event type to register for
- * @cb: function to remove from event
+ * @cb: function to invoke when event fires
- * @opaque: data blob to pass to callback
+ * @opaque: data blob to pass to @callback
  * @freecb: callback to free @opaque
  * @callbackID: filled with callback ID
  *
- * Register the function @callbackID with connection @conn,
+ * Register the function @cb with connection @conn, from @state, for
- * from @state, for events of type @eventID.
+ * events of type @eventID, and return the registration handle in
+ * @callbackID.
  *
  * Returns: the number of callbacks now registered, or -1 on error
  */

src/conf/network_event.c

@@ -1,6 +1,7 @@
 /*
  * network_event.c: network event queue processing helpers
  *
+ * Copyright (C) 2014 Red Hat, Inc.
  * Copyright (C) 2013 SUSE LINUX Products GmbH, Nuernberg, Germany.
  *
  * This library is free software; you can redistribute it and/or
@@ -31,7 +32,7 @@
 struct _virNetworkEvent {
     virObjectEvent parent;
 
-    /* Unused attribute to get virNetworkEvent class being created */
+    /* Unused attribute to allow for subclass creation */
     bool dummy;
 };
 typedef struct _virNetworkEvent virNetworkEvent;
@@ -71,7 +72,7 @@ virNetworkEventsOnceInit(void)
 
 VIR_ONCE_GLOBAL_INIT(virNetworkEvents)
 
-void
+static void
 virNetworkEventDispose(void *obj)
 {
     virNetworkEventPtr event = obj;
@@ -79,7 +80,7 @@ virNetworkEventDispose(void *obj)
 }
 
 
-void
+static void
 virNetworkEventLifecycleDispose(void *obj)
 {
     virNetworkEventLifecyclePtr event = obj;
@@ -126,13 +127,14 @@ cleanup:
  * @state: object event state
  * @net: network to filter on or NULL for all networks
  * @eventID: ID of the event type to register for
- * @cb: function to add to event
+ * @cb: function to invoke when event occurs
- * @opaque: data blob to pass to callback
+ * @opaque: data blob to pass to @callback
  * @freecb: callback to free @opaque
  * @callbackID: filled with callback ID
  *
- * Register the function @callbackID with connection @conn,
+ * Register the function @cb with connection @conn, from @state, for
- * from @state, for events of type @eventID.
+ * events of type @eventID, and return the registration handle in
+ * @callbackID.
  *
  * Returns: the number of callbacks now registered, or -1 on error
  */
@@ -161,6 +163,16 @@ virNetworkEventStateRegisterID(virConnectPtr conn,
                                              cb, opaque, freecb, callbackID);
 }
 
+
+/**
+ * virNetworkEventLifecycleNew:
+ * @name: name of the network object the event describes
+ * @uuid: uuid of the network object the event describes
+ * @type: type of lifecycle event
+ * @detail: more details about @type
+ *
+ * Create a new network lifecycle event.
+ */
 virObjectEventPtr
 virNetworkEventLifecycleNew(const char *name,
                             const unsigned char *uuid,

src/conf/object_event.c

@@ -1,7 +1,7 @@
 /*
  * object_event.c: object event queue processing helpers
  *
- * Copyright (C) 2010-2013 Red Hat, Inc.
+ * Copyright (C) 2010-2014 Red Hat, Inc.
  * Copyright (C) 2008 VirtualIron
  * Copyright (C) 2013 SUSE LINUX Products GmbH, Nuernberg, Germany.
  *
@@ -43,7 +43,6 @@ struct _virObjectEventQueue {
 
 static virClassPtr virObjectEventClass;
 
-static virClassPtr virObjectEventClass;
 static void virObjectEventDispose(void *obj);
 
 static int
@@ -60,6 +59,12 @@ virObjectEventOnceInit(void)
 
 VIR_ONCE_GLOBAL_INIT(virObjectEvent)
 
+/**
+ * virClassForObjectEvent:
+ *
+ * Return the class object to be used as a parent when creating an
+ * event subclass.
+ */
 virClassPtr
 virClassForObjectEvent(void)
 {
@@ -233,7 +238,8 @@ virObjectEventCallbackListPurgeMarked(virObjectEventCallbackListPtr cbList)
  * @klass: the base event class
  * @eventID: the event ID
  * @callback: the callback to add
- * @opaque: opaque data tio pass to callback
+ * @opaque: opaque data to pass to @callback
+ * @freecb: callback to free @opaque
  * @callbackID: filled with callback ID
  *
  * Internal function to add a callback from a virObjectEventCallbackListPtr
@@ -399,18 +405,33 @@ virObjectEventQueueNew(void)
     return ret;
 }
 
+
+/**
+ * virObjectEventStateLock:
+ * @state: the event state object
+ *
+ * Lock event state before calling functions from object_event_private.h.
+ */
 void
 virObjectEventStateLock(virObjectEventStatePtr state)
 {
     virMutexLock(&state->lock);
 }
 
+
+/**
+ * virObjectEventStateUnlock:
+ * @state: the event state object
+ *
+ * Unlock event state after calling functions from object_event_private.h.
+ */
 void
 virObjectEventStateUnlock(virObjectEventStatePtr state)
 {
     virMutexUnlock(&state->lock);
 }
 
+
 /**
  * virObjectEventStateFree:
  * @list: virObjectEventStatePtr to free
@@ -436,6 +457,16 @@ virObjectEventStateFree(virObjectEventStatePtr state)
 
 static void virObjectEventStateFlush(virObjectEventStatePtr state);
 
+
+/**
+ * virObjectEventTimer:
+ * @timer: id of the event loop timer
+ * @opaque: the event state object
+ *
+ * Register this function with the event state as its opaque data as
+ * the callback of a periodic timer on the event loop, in order to
+ * flush the callback queue.
+ */
 void
 virObjectEventTimer(int timer ATTRIBUTE_UNUSED, void *opaque)
 {
@@ -444,8 +475,11 @@ virObjectEventTimer(int timer ATTRIBUTE_UNUSED, void *opaque)
     virObjectEventStateFlush(state);
 }
 
+
 /**
  * virObjectEventStateNew:
+ *
+ * Allocate a new event state object.
  */
 virObjectEventStatePtr
 virObjectEventStateNew(void)
@@ -477,6 +511,18 @@ error:
     return NULL;
 }
 
+
+/**
+ * virObjectEventNew:
+ * @klass: subclass of event to be created
+ * @dispatcher: callback for dispatching the particular subclass of event
+ * @eventID: id of the event
+ * @id: id of the object the event describes, or 0
+ * @name: name of the object the event describes
+ * @uuid: uuid of the object the event describes
+ *
+ * Create a new event, with the information common to all events.
+ */
 void *
 virObjectEventNew(virClassPtr klass,
                   virObjectEventDispatchFunc dispatcher,
@@ -514,6 +560,7 @@ virObjectEventNew(virClassPtr klass,
     return event;
 }
 
+
 /**
  * virObjectEventQueuePush:
  * @evtQueue: the object event queue
@@ -560,7 +607,7 @@ virObjectEventDispatchMatchCallback(virObjectEventPtr event,
          * will cause problems when a domain switches between
          * running & shutoff states & ignoring 'name' since
          * Xen sometimes renames guests during migration, thus
-         * leaving 'uuid' as the only truly reliable ID we can use*/
+         * leaving 'uuid' as the only truly reliable ID we can use. */
 
         if (memcmp(event->meta.uuid, cb->meta->uuid, VIR_UUID_BUFLEN) == 0)
             return 1;
@@ -613,6 +660,16 @@ virObjectEventStateQueueDispatch(virObjectEventStatePtr state,
     queue->count = 0;
 }
 
+
+/**
+ * virObjectEventStateQueue:
+ * @state: the event state object
+ * @event: event to add to the queue
+ *
+ * Adds @event to the queue of events to be dispatched at the next
+ * safe moment.  The caller should no longer use @event after this
+ * call.
+ */
 void
 virObjectEventStateQueue(virObjectEventStatePtr state,
                          virObjectEventPtr event)
@@ -667,15 +724,19 @@ virObjectEventStateFlush(virObjectEventStatePtr state)
  * virObjectEventStateRegisterID:
  * @conn: connection to associate with callback
  * @state: domain event state
+ * @uuid: uuid of the object for event filtering
+ * @name: name of the object for event filtering
+ * @id: id of the object for event filtering, or 0
  * @klass: the base event class
  * @eventID: ID of the event type to register for
- * @cb: function to remove from event
+ * @cb: function to invoke when event occurs
- * @opaque: data blob to pass to callback
+ * @opaque: data blob to pass to @callback
  * @freecb: callback to free @opaque
  * @callbackID: filled with callback ID
  *
- * Register the function @callbackID with connection @conn,
+ * Register the function @cb with connection @conn, from @state, for
- * from @state, for events of type @eventID.
+ * events of type @eventID, and return the registration handle in
+ * @callbackID.
  *
  * Returns: the number of callbacks now registered, or -1 on error
  */
@@ -746,7 +807,8 @@ virObjectEventStateDeregisterID(virConnectPtr conn,
     virObjectEventStateLock(state);
     if (state->isDispatching)
         ret = virObjectEventCallbackListMarkDeleteID(conn,
-                                                     state->callbacks, callbackID);
+                                                     state->callbacks,
+                                                     callbackID);
     else
         ret = virObjectEventCallbackListRemoveID(conn,
                                                  state->callbacks, callbackID);

src/conf/object_event.h

@@ -1,7 +1,7 @@
 /*
  * object_event.h: object event queue processing helpers
  *
- * Copyright (C) 2012 Red Hat, Inc.
+ * Copyright (C) 2012-2014 Red Hat, Inc.
  * Copyright (C) 2008 VirtualIron
  * Copyright (C) 2013 SUSE LINUX Products GmbH, Nuernberg, Germany.
  *
@@ -47,7 +47,7 @@ void virObjectEventStateFree(virObjectEventStatePtr state);
 virObjectEventStatePtr
 virObjectEventStateNew(void);
 
-/*
+/**
  * virConnectObjectEventGenericCallback:
  * @conn: the connection pointer
  * @obj: the object pointer
@@ -60,7 +60,8 @@ typedef void (*virConnectObjectEventGenericCallback)(virConnectPtr conn,
                                                      void *obj,
                                                      void *opaque);
 
-# define VIR_OBJECT_EVENT_CALLBACK(cb) ((virConnectObjectEventGenericCallback)(cb))
+# define VIR_OBJECT_EVENT_CALLBACK(cb) \
+    ((virConnectObjectEventGenericCallback)(cb))
 
 void
 virObjectEventStateQueue(virObjectEventStatePtr state,

src/libvirt_private.syms

@@ -534,6 +534,11 @@ virNetworkSetBridgeName;
 virPortGroupFindByName;
 
 
+# conf/network_event.h
+virNetworkEventLifecycleNew;
+virNetworkEventStateRegisterID;
+
+
 # conf/node_device_conf.h
 virNodeDevCapsDefFree;
 virNodeDevCapTypeFromString;
@@ -624,8 +629,6 @@ virNWFilterVarValueGetSimple;
 
 
 # conf/object_event.h
-virNetworkEventLifecycleNew;
-virNetworkEventStateRegisterID;
 virObjectEventStateDeregisterID;
 virObjectEventStateEventID;
 virObjectEventStateFree;