diff --git a/src/common/pico_time/include/pico/time.h b/src/common/pico_time/include/pico/time.h
index a7a00b8..e5a6a39 100644
--- a/src/common/pico_time/include/pico/time.h
+++ b/src/common/pico_time/include/pico/time.h
@@ -143,9 +143,13 @@ static inline absolute_time_t make_timeout_time_ms(uint32_t ms) {
 /*! \brief Return the difference in microseconds between two timestamps
  * \ingroup timestamp
  *
+ * \note be careful when diffing against large timestamps (e.g. \ref at_the_end_of_time)
+ * as the signed integer may overflow.
+ *
  * \param from the first timestamp
  * \param to the second timestamp
- * \return the number of microseconds between the two timestamps (positive if `to` is after `from`)
+ * \return the number of microseconds between the two timestamps (positive if `to` is after `from` except
+ * in case of overflow)
  */
 static inline int64_t absolute_time_diff_us(absolute_time_t from, absolute_time_t to) {
     return to_us_since_boot(to) - to_us_since_boot(from);
diff --git a/src/common/pico_time/time.c b/src/common/pico_time/time.c
index df913f8..e004c00 100644
--- a/src/common/pico_time/time.c
+++ b/src/common/pico_time/time.c
@@ -14,7 +14,6 @@
 #include "hardware/gpio.h"
 
 const absolute_time_t ABSOLUTE_TIME_INITIALIZED_VAR(nil_time, 0);
-// use LONG_MAX not ULONG_MAX so we don't have sign overflow in time diffs
 const absolute_time_t ABSOLUTE_TIME_INITIALIZED_VAR(at_the_end_of_time, ULONG_MAX);
 
 typedef struct alarm_pool_entry {