pico_time comment changes: remove stale comment, include warning about integer overflow

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);

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 {