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

At Tue, 4 Feb 2014 10:23:22 +0000, Daniel P. Berrange wrote: > > On Tue, Feb 04, 2014 at 10:07:58AM +0100, Claudio Bley wrote: > > 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... > > Yes, it is basically saying that unless you have called it with a timer > id that is invalid, it is guaranteed to succeed to change the frequency. Thank you, that clears it up. Would it make sense to reword or even remove that sentence? Because it implies that it will fail when the timer does NOT exist?