doc: document the event timestamps

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

1 files changed, 42 insertions, 0 deletions

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
  */