Fixes for documentation extraction

* include/libvirt/libvirt.h.in: some of the function type description
  were broken so they could not be automatically documented
* src/util/event.c docs/apibuild.py: event.c exports one public API
  so it needs to be scanned too, avoid a few warnings

diff --git a/docs/apibuild.py b/docs/apibuild.py
index 2dda4df1bab88b8e8e0f45b60eb162c4fd909644..62b75575bdcce506cfd05b1c4b561f9713c96690 100755 (executable)
--- a/docs/apibuild.py
+++ b/docs/apibuild.py
@@ -22,6 +22,7 @@ included_files = {
   "virterror.h": "header with error specific API definitions",
   "libvirt.c": "Main interfaces for the libvirt library",
   "virterror.c": "implements error handling and reporting code for libvirt",
+  "event.c": "event loop for monitoring file handles",
 }
 
 ignored_words = {
@@ -43,6 +44,12 @@ ignored_functions = {
   "virDomainMigratePrepareTunnel": "private function for tunnelled migration",
   "virDrvSupportsFeature": "private function for remote access",
   "DllMain": "specific function for Win32",
+  "virEventAddHandle": "internal function in event.c",
+  "virEventUpdateHandle": "internal function in event.c",
+  "virEventRemoveHandle": "internal function in event.c",
+  "virEventAddTimeout": "internal function in event.c",
+  "virEventUpdateTimeout": "internal function in event.c",
+  "virEventRemoveTimeout": "internal function in event.c",
 }
 
 def escape(raw):

diff --git a/include/libvirt/libvirt.h.in b/include/libvirt/libvirt.h.in
index ca8e6fad10f69bc274ea824aa93e1e0903614f08..2eba61ee50f19e2db97288bfcfcc20a7e217f1a0 100644 (file)
--- a/include/libvirt/libvirt.h.in
+++ b/include/libvirt/libvirt.h.in
@@ -490,19 +490,17 @@ typedef virConnectCredential *virConnectCredentialPtr;
 
 
 /**
- * virConnectCredCallbackPtr
- *
- * @param authtype type of authentication being performed
- * @param cred list of virConnectCredential object to fetch from user
- * @param ncred size of cred list
- * @param cbdata opaque data passed to virConnectOpenAuth
+ * virConnectAuthCallbackPtr:
+ * @cred: list of virConnectCredential object to fetch from user
+ * @ncred: size of cred list
+ * @cbdata: opaque data passed to virConnectOpenAuth
  *
  * When authentication requires one or more interactions, this callback
  * is invoked. For each interaction supplied, data must be gathered
  * from the user and filled in to the 'result' and 'resultlen' fields.
  * If an interaction can not be filled, fill in NULL and 0.
  *
- * Return 0 if all interactions were filled, or -1 upon error
+ * Returns 0 if all interactions were filled, or -1 upon error
  */
 typedef int (*virConnectAuthCallbackPtr)(virConnectCredentialPtr cred,
                                          unsigned int ncred,
@@ -1578,6 +1576,14 @@ typedef int (*virConnectDomainEventCallback)(virConnectPtr conn,
                                              int detail,
                                              void *opaque);
 
+/*
+ * virFreeCallback:
+ * @opaque: opaque user data provided at registration
+ *
+ * Type for a domain event callback when the event is deregistered and
+ * need to be freed, @opaque is provided along with the callback at
+ * registration time
+ */
 typedef void (*virFreeCallback)(void *opaque);
 
 int virConnectDomainEventRegister(virConnectPtr conn,
@@ -2071,8 +2077,15 @@ int virDomainSnapshotDelete(virDomainSnapshotPtr snapshot,
 
 int virDomainSnapshotFree(virDomainSnapshotPtr snapshot);
 
-/* A generic callback definition. Specific events usually have a customization
- * with extra parameters */
+/*
+ * 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
+ */
 typedef void (*virConnectDomainEventGenericCallback)(virConnectPtr conn,
                                                      virDomainPtr dom,
                                                      void *opaque);
@@ -2135,7 +2148,7 @@ typedef enum {
 
 
 /**
- * virConnectDomainEventWatchdogCallback:
+ * virConnectDomainEventIOErrorCallback:
  * @conn: connection object
  * @dom: domain on which the event occurred
  * @srcPath: The host file on which the IO error occurred
@@ -2145,7 +2158,6 @@ typedef enum {
  *
  * The callback signature to use when registering for an event of type
  * VIR_DOMAIN_EVENT_ID_IO_ERROR with virConnectDomainEventRegisterAny()
- *
  */
 typedef void (*virConnectDomainEventIOErrorCallback)(virConnectPtr conn,
                                                      virDomainPtr dom,
@@ -2155,7 +2167,7 @@ typedef void (*virConnectDomainEventIOErrorCallback)(virConnectPtr conn,
                                                      void *opaque);
 
 /**
- * virConnectDomainEventWatchdogCallback:
+ * virConnectDomainEventIOErrorReasonCallback:
  * @conn: connection object
  * @dom: domain on which the event occurred
  * @srcPath: The host file on which the IO error occurred

diff --git a/src/util/event.c b/src/util/event.c
index 59b9ac6212bff8e31525b291a554a82d760d3b92..680fef91318386ffb37e708f643f5679ee4209fe 100644 (file)
--- a/src/util/event.c
+++ b/src/util/event.c
@@ -79,13 +79,14 @@ int virEventRemoveTimeout(int timer) {
 
 /**
  * virEventRegisterImpl:
- * Register an EventImpl
  * @addHandle: the callback to add fd handles
  * @updateHandle: the callback to update fd handles
  * @removeHandle: the callback to remove fd handles
  * @addTimeout: the callback to add a timeout
  * @updateTimeout: the callback to update a timeout
  * @removeTimeout: the callback to remove a timeout
+ *
+ * Registers an event implementation
  */
 void virEventRegisterImpl(virEventAddHandleFunc addHandle,
                           virEventUpdateHandleFunc updateHandle,