[PATCH libinput 3/3] Expand documentation for libinput_udev_create_for_seat

[Peter Hutterer]

On Fri, Mar 21, 2014 at 09:18:42PM +0100, Jonas Ådahl wrote:
> On Fri, Mar 21, 2014 at 02:13:22PM +1000, Peter Hutterer wrote:
> > Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> > ---
> >  src/libinput.h | 6 ++++++
> >  1 file changed, 6 insertions(+)
> > 
> > diff --git a/src/libinput.h b/src/libinput.h
> > index d6bf9f8..3e09871 100644
> > --- a/src/libinput.h
> > +++ b/src/libinput.h
> > @@ -691,6 +691,12 @@ struct libinput_interface {
> >   * the given seat ID. New devices or devices removed will appear as events
> >   * during libinput_dispatch.
> >   *
> > + * libinput_udev_create_for_seat() fails for internal values only. No
> 
> What does internal values mean?  It fails for invalid input, OOM, libudev
> errors, etc, but how is that relevant? Maybe its enough to just say that
> this call will not fail even if no input devices are successfully added,
> and that if not supported, or if failed to open, devices will be ignored
> until next resume.

huh, this should have been "internal errors", which should make a bit more
sense. and yes, the above was pretty much what I was trying to say. I've
reworded this now to:

 libinput_udev_create_for_seat() succeeds even if no input device is
 available in this seat, or if devices are available but fail to open in
 @ref libinput_interface::open_restricted. Devices that do not have the
 minimum capabilities to be recognized as pointer, keyboard or touch
 device are ignored. Such devices and those that failed to open are
 ignored until the next call to libinput_resume().

Cheers,
   Peter

> 
> > + * guarantee is made that a device is available once the call finishes, and
> > + * only devices handled by libinput are avialable. Devices that cannot be
> > + * opened in @ref libinput_interface::open_restricted or do not match
> > + * libinput requirements are ignored.
> > + *
> >   * @param interface The callback interface
> >   * @param user_data Caller-specific data passed to the various callback
> >   * interfaces.
> > -- 
> > 1.8.5.3
> >