Add a documentation note to update the slot after syncing

Clients may not care about the events generated during SYN_DROPPED, but the
current slot must be updated to avoid a client being out-of-date.
Same with tracking IDs, if they changed, the caller will likely have to update
some internal states.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Reviewed-by: Benjamin Tissoires <benjamin.tissoires@gmail.com>

diff --git a/libevdev/libevdev.h b/libevdev/libevdev.h
index 6920a763390cfe50201d59322577f73dbf709b6f..481e378be0b16e6d15578924c44040410a01ef92 100644 (file)
--- a/libevdev/libevdev.h
+++ b/libevdev/libevdev.h
@@ -707,7 +707,11 @@ enum libevdev_read_status {
  * If a device needs to be synced by the caller but the caller does not call
  * with the @ref LIBEVDEV_READ_FLAG_SYNC flag set, all events from the diff are
  * dropped after libevdev updates its internal state and event processing
- * continues as normal.
+ * continues as normal. Note that the current slot and the state of touch
+ * points may have updated during the SYN_DROPPED event, it is strongly
+ * recommended that a caller ignoring all sync events calls
+ * libevdev_get_current_slot() and checks the ABS_MT_TRACKING_ID values for
+ * all slots.
  *
  * If a device has changed state without events being enqueued in libevdev,
  * e.g. after changing the file descriptor, use the @ref