docs: don't ignore virEvent API

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.

diff --git a/docs/apibuild.py b/docs/apibuild.py
index e5cbbe8924260ac0af8704cc259359f18d0541de..2bdbf2dd57accf5f0c53dd270497994e9a889ddc 100755 (executable)
--- 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 6900011c030271539d1dfda1b33a45e00fd0f12d..886cb6d3058ebf5c0756c46797127c05bbbb1ba0 100644 (file)
--- 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;