Re: [libvirt] [PATCH] event: improve public API docs

At Tue, 31 Dec 2013 08:21:29 -0700, Eric Blake wrote: > > @@ -132,17 +151,20 @@ virEventAddTimeout(int timeout, > * @timer: timer id to change > * @timeout: time between events in milliseconds > * > - * Change frequency for a timer. > + * Change frequency for a timer. This function > + * requires that an event loop has previously been registered with > + * virEventRegisterImpl() or virEventRegisterDefaultImpl(). > * > * 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 > + * Will not fail if timer exists. > */ > void > virEventUpdateTimeout(int timer, int timeout) > { I just stumbled over the last sentence in this function's documentation. What exactly is this meant to tell me? On first thought I figured this to be a typo, actually meaning "it will not fail if timer does not exist" (ie. just ignore the change request)? Or, is it just to assure that the function will work (ie. change the frequency of the timer) in any circumstances iff only the timer exists in the first place? But, then again, the function cannot fail since its return type is void. So, I'd assume that the function will just always work anyway...