[libvirt] [PATCH] docs: don't ignore virEvent API

[Eric Blake]

Commit 6094ad7b (0.9.3 release) promoted several functions from
internal to public, but forgot to fix the documentation generator
to provide details about those functions.

For an example of what this fixes, look at:
file:///path/to/libvirt/docs/html/libvirt-libvirt.html#virEventAddHandle
before and after the patch.

* docs/apibuild.py (ignored_functions): Don't ignore functions
that were turned into official API.
* src/util/virevent.c: Fix comments to pass through parser.
---

In response to my concerns raised on one of Claudio's patches:
https://www.redhat.com/archives/libvir-list/2013-February/msg00048.html

 docs/apibuild.py    |  6 -----
 src/util/virevent.c | 78 +++++++++++++++++++++++++++++++++++------------------
 2 files changed, 52 insertions(+), 32 deletions(-)

diff --git a/docs/apibuild.py b/docs/apibuild.py
index e5cbbe8..2bdbf2d 100755
--- a/docs/apibuild.py
+++ b/docs/apibuild.py
@@ -64,12 +64,6 @@ ignored_functions = {
   "virDomainMigratePrepareTunnel3": "private function for tunnelled migration",
   "virDrvSupportsFeature": "private function for remote access",
   "DllMain": "specific function for Win32",
-  "virEventAddHandle": "internal function in virevent.c",
-  "virEventUpdateHandle": "internal function in virevent.c",
-  "virEventRemoveHandle": "internal function in virevent.c",
-  "virEventAddTimeout": "internal function in virevent.c",
-  "virEventUpdateTimeout": "internal function in virevent.c",
-  "virEventRemoveTimeout": "internal function in virevent.c",
   "virTypedParameterArrayValidate": "internal function in virtypedparam.c",
   "virTypedParameterAssign": "internal function in virtypedparam.c",
   "virTypedParameterAssignFromStr": "internal function in virtypedparam.c",
diff --git a/src/util/virevent.c b/src/util/virevent.c
index 6900011..886cb6d 100644
--- a/src/util/virevent.c
+++ b/src/util/virevent.c
@@ -1,7 +1,7 @@
 /*
  * virevent.c: event loop for monitoring file handles
  *
- * Copyright (C) 2007, 2011 Red Hat, Inc.
+ * Copyright (C) 2007, 2011, 2013 Red Hat, Inc.
  * Copyright (C) 2007 Daniel P. Berrange
  *
  * This library is free software; you can redistribute it and/or
@@ -38,20 +38,25 @@ static virEventUpdateTimeoutFunc updateTimeoutImpl = NULL;
 static virEventRemoveTimeoutFunc removeTimeoutImpl = NULL;

 /**
- * virEventAddHandle: register a callback for monitoring file handle events
+ * virEventAddHandle:
  *
  * @fd: file handle to monitor for events
  * @events: bitset of events to watch from virEventHandleType constants
  * @cb: callback to invoke when an event occurs
  * @opaque: user data to pass to callback
+ * @ff: callback to free opaque when handle is removed
  *
- * returns -1 if the file handle cannot be registered, 0 upon success
+ * Register a callback for monitoring file handle events.
+ *
+ * Returns -1 if the file handle cannot be registered, 0 upon success
  */
-int virEventAddHandle(int fd,
-                      int events,
-                      virEventHandleCallback cb,
-                      void *opaque,
-                      virFreeCallback ff) {
+int
+virEventAddHandle(int fd,
+                  int events,
+                  virEventHandleCallback cb,
+                  void *opaque,
+                  virFreeCallback ff)
+{
     if (!addHandleImpl)
         return -1;

@@ -59,25 +64,33 @@ int virEventAddHandle(int fd,
 }

 /**
- * virEventUpdateHandle: change event set for a monitored file handle
+ * virEventUpdateHandle:
  *
  * @watch: watch whose file handle to update
  * @events: bitset of events to watch from virEventHandleType constants
  *
+ * Change event set for a monitored file handle.
+ *
  * Will not fail if fd exists
  */
-void virEventUpdateHandle(int watch, int events) {
+void
+virEventUpdateHandle(int watch, int events)
+{
     updateHandleImpl(watch, events);
 }

 /**
- * virEventRemoveHandle: unregister a callback from a file handle
+ * virEventRemoveHandle:
  *
  * @watch: watch whose file handle to remove
  *
- * returns -1 if the file handle was not registered, 0 upon success
+ * Unregister a callback from a file handle.
+ *
+ * Returns -1 if the file handle was not registered, 0 upon success.
  */
-int virEventRemoveHandle(int watch) {
+int
+virEventRemoveHandle(int watch)
+{
     if (!removeHandleImpl)
         return -1;

@@ -85,22 +98,27 @@ int virEventRemoveHandle(int watch) {
 }

 /**
- * virEventAddTimeout: register a callback for a timer event
+ * virEventAddTimeout:
  *
  * @timeout: time between events in milliseconds
  * @cb: callback to invoke when an event occurs
  * @opaque: user data to pass to callback
+ * @ff: callback to free opaque when timeout is removed
+ *
+ * Register a callback for a timer event.
  *
  * Setting timeout to -1 will disable the timer. Setting the timeout
  * to zero will cause it to fire on every event loop iteration.
  *
- * returns -1 if the timer cannot be registered, a positive
- * integer timer id upon success
+ * Returns -1 if the timer cannot be registered, a positive
+ * integer timer id upon success.
  */
-int virEventAddTimeout(int timeout,
-                       virEventTimeoutCallback cb,
-                       void *opaque,
-                       virFreeCallback ff) {
+int
+virEventAddTimeout(int timeout,
+                   virEventTimeoutCallback cb,
+                   void *opaque,
+                   virFreeCallback ff)
+{
     if (!addTimeoutImpl)
         return -1;

@@ -108,28 +126,36 @@ int virEventAddTimeout(int timeout,
 }

 /**
- * virEventUpdateTimeoutImpl: change frequency for a timer
+ * virEventUpdateTimeout:
  *
  * @timer: timer id to change
- * @frequency: time between events in milliseconds
+ * @timeout: time between events in milliseconds
+ *
+ * Change frequency for a timer.
  *
  * Setting frequency to -1 will disable the timer. Setting the frequency
  * to zero will cause it to fire on every event loop iteration.
  *
  * Will not fail if timer exists
  */
-void virEventUpdateTimeout(int timer, int timeout) {
+void
+virEventUpdateTimeout(int timer, int timeout)
+{
     updateTimeoutImpl(timer, timeout);
 }

 /**
- * virEventRemoveTimeout: unregister a callback for a timer
+ * virEventRemoveTimeout:
  *
  * @timer: the timer id to remove
  *
- * returns -1 if the timer was not registered, 0 upon success
+ * Unregister a callback for a timer.
+ *
+ * Returns -1 if the timer was not registered, 0 upon success.
  */
-int virEventRemoveTimeout(int timer) {
+int
+virEventRemoveTimeout(int timer)
+{
     if (!removeTimeoutImpl)
         return -1;

-- 
1.8.1