[PATCH libinput] doc: document the event timestamps

[Peter Hutterer]

Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
---
 doc/Makefile.am        |  1 +
 doc/page-hierarchy.dox |  3 ++-
 doc/timestamps.dox     | 36 ++++++++++++++++++++++++++++++++++++
 src/libinput.h         | 42 ++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 81 insertions(+), 1 deletion(-)
 create mode 100644 doc/timestamps.dox

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 5391f22..382f64d 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -27,6 +27,7 @@ header_files = \
 	$(srcdir)/tablet-support.dox \
 	$(srcdir)/tapping.dox \
 	$(srcdir)/test-suite.dox \
+	$(srcdir)/timestamps.dox \
 	$(srcdir)/tools.dox \
 	$(srcdir)/touchpad-jumping-cursors.dox \
 	$(srcdir)/touchpad-pressure.dox \
diff --git a/doc/page-hierarchy.dox b/doc/page-hierarchy.dox
index 65749fe..1f0b735 100644
--- a/doc/page-hierarchy.dox
+++ b/doc/page-hierarchy.dox
@@ -24,10 +24,11 @@
 
 - @subpage tablet-support
 
- at page general General setup
+ at page general General 
 
 - @subpage udev_config
 - @subpage seats
+- @subpage timestamps
 
 @page misc Users
 
diff --git a/doc/timestamps.dox b/doc/timestamps.dox
new file mode 100644
index 0000000..a823c00
--- /dev/null
+++ b/doc/timestamps.dox
@@ -0,0 +1,36 @@
+/**
+
+ at page timestamps Timestamps
+
+ at section event_timestamps Event timestamps
+
+Most libinput events provide a timestamp in millisecond and/or microsecond
+resolution. These timestamp usually increase monotonically, but libinput
+does not guarantee that this always the case. In other words, it is possible
+to receive an event with a timestamp earlier than the previous event. 
+
+For example, if a touchpad has @ref tapping enabled, a button event may have a
+lower timestamp than an event from a different device. Tapping requires the
+use of timeouts to detect multi-finger taps and/or @ref tapndrag.
+
+Consider the following event sequences from a touchpad and a mouse:
+
+<pre>
+Time      Touchpad      Mouse
+---------------------------------
+t1       finger down
+t2        finger up
+t3                     movement
+t4       tap timeout
+</pre>
+
+For this event sequence, the first event to be sent to a caller is in
+response to the mouse movement: an event of type @ref
+LIBINPUT_EVENT_POINTER_MOTION with the timestamp t3.
+Once the timeout expires at t4, libinput generates an event of 
+ at ref LIBINPUT_EVENT_POINTER_BUTTON (press) with a timestamp t1 and an event
+ at ref LIBINPUT_EVENT_POINTER_BUTTON (release) with a timestamp t2.
+
+Thus, the caller gets events with timestamps in the order t3, t1, t2,
+despite t3 > t2 > t1.
+*/
diff --git a/src/libinput.h b/src/libinput.h
index 430fe18..54bbc7f 100644
--- a/src/libinput.h
+++ b/src/libinput.h
@@ -972,6 +972,9 @@ libinput_event_device_notify_get_base_event(struct libinput_event_device_notify
 /**
  * @ingroup event_keyboard
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @return The event time for this event
  */
 uint32_t
@@ -980,6 +983,9 @@ libinput_event_keyboard_get_time(struct libinput_event_keyboard *event);
 /**
  * @ingroup event_keyboard
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @return The event time for this event in microseconds
  */
 uint64_t
@@ -1035,6 +1041,9 @@ libinput_event_keyboard_get_seat_key_count(
 /**
  * @ingroup event_pointer
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @return The event time for this event
  */
 uint32_t
@@ -1043,6 +1052,9 @@ libinput_event_pointer_get_time(struct libinput_event_pointer *event);
 /**
  * @ingroup event_pointer
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @return The event time for this event in microseconds
  */
 uint64_t
@@ -1400,6 +1412,9 @@ libinput_event_pointer_get_base_event(struct libinput_event_pointer *event);
 /**
  * @ingroup event_touch
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @return The event time for this event
  */
 uint32_t
@@ -1408,6 +1423,9 @@ libinput_event_touch_get_time(struct libinput_event_touch *event);
 /**
  * @ingroup event_touch
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @return The event time for this event in microseconds
  */
 uint64_t
@@ -1564,6 +1582,9 @@ libinput_event_touch_get_base_event(struct libinput_event_touch *event);
 /**
  * @ingroup event_gesture
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @return The event time for this event
  */
 uint32_t
@@ -1572,6 +1593,9 @@ libinput_event_gesture_get_time(struct libinput_event_gesture *event);
 /**
  * @ingroup event_gesture
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @return The event time for this event in microseconds
  */
 uint64_t
@@ -2300,6 +2324,9 @@ libinput_event_tablet_tool_get_seat_button_count(struct libinput_event_tablet_to
 /**
  * @ingroup event_tablet
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @param event The libinput tablet tool event
  * @return The event time for this event
  */
@@ -2309,6 +2336,9 @@ libinput_event_tablet_tool_get_time(struct libinput_event_tablet_tool *event);
 /**
  * @ingroup event_tablet
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @param event The libinput tablet tool event
  * @return The event time for this event in microseconds
  */
@@ -2735,6 +2765,9 @@ libinput_event_tablet_pad_get_mode_group(struct libinput_event_tablet_pad *event
 /**
  * @ingroup event_tablet
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @param event The libinput tablet pad event
  * @return The event time for this event
  */
@@ -2744,6 +2777,9 @@ libinput_event_tablet_pad_get_time(struct libinput_event_tablet_pad *event);
 /**
  * @ingroup event_tablet_pad
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @param event The libinput tablet pad event
  * @return The event time for this event in microseconds
  */
@@ -2799,6 +2835,9 @@ libinput_event_switch_get_base_event(struct libinput_event_switch *event);
 /**
  * @ingroup event_switch
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @param event The libinput switch event
  * @return The event time for this event
  */
@@ -2808,6 +2847,9 @@ libinput_event_switch_get_time(struct libinput_event_switch *event);
 /**
  * @ingroup event_switch
  *
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
  * @param event The libinput switch event
  * @return The event time for this event in microseconds
  */
-- 
2.9.3