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

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.