Elaborate description of time module additions.

Hardware-API.md

@@ -398,12 +398,19 @@ Wake reason:
 # time module additions
 
 The time module has uPy specific functions:
-- `time.sleep_ms(ms)` NOHEAP
-- `time.sleep_us(us)` NOHEAP
-- `time.ticks_ms()` NOHEAP
-- `time.ticks_us()` NOHEAP
-- `time.ticks_cpu()` NOHEAP
-- `time.ticks_diff(t0, t1)` NOHEAP
+- `time.sleep_ms(ms)` NOHEAP - Delay for given number of milliseconds, should be positive or 0
+- `time.sleep_us(us)` NOHEAP - Delay for given number of microseconds, should be positive or 0
+- `time.ticks_ms()` NOHEAP  - Return increasing millisecond counter with arbitrary reference point, and wrapping after some (unspecified) value. The value should be treated as opaque, suitable for use only with ticks_diff().
+- `time.ticks_us()` NOHEAP - As above, but microsecond counter.
+- `time.ticks_cpu()` NOHEAP - As above, but highest resolution available (usually CPU clocks).
+- `time.ticks_diff(old, new)` NOHEAP - Measure period between consecutive calls to ticks_ms(), ticks_us(), or ticks_cpu(). Value returned by these functions may wrap around at any time, so directly subtracting them is not supported. ticks_diff() should be used instead. "old" value should actually precede "new" value in time, or result is undefined. This function should not be used to measure arbitrarily long periods of time (because ticks_*() functions wrap around and usually would have short period). The expected usage pattern is implementing event polling with timeout:
+```
+# Wait for GPIO pin to be asserted, but at most 500us
+start = time.ticks_us()
+while pin.value() == 0:
+    if time.ticks_diff(start, time.ticks_us()) > 500:
+        raise TimeoutError
+```
 - `time.source(rtc_or_timer_obj)` attach a RTC to use as the time reference for `time.time()` and `time.localtime()`.
 
 # os module additions