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

[Osier Yang]

On 2013年02月02日 07:04, Eric Blake wrote:
> 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;
>

ACK.