[libvirt] [PATCH] docs: don't ignore virEvent API
Osier Yang
jyang at redhat.com
Sat Feb 2 02:13:10 UTC 2013
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.
More information about the libvir-list
mailing list