docs/utime: Add docs for ticks_add(), improvements for other ticks_*().

1 files changed, 44 insertions, 8 deletions

diff --git a/docs/library/utime.rst b/docs/library/utime.rst
index 8fa5cb1759..109c3560cc 100644
--- a/docs/library/utime.rst
+++ b/docs/library/utime.rst
@@ -89,15 +89,16 @@ Functions
         to be a power of two, but otherwise may differ from port to port. The same
         period value is used for all of ticks_ms(), ticks_us(), ticks_cpu() functions
         (for simplicity). Thus, these functions will return a value in range
-        [0 .. `TICKS_MAX`], inclusive, total `TICKS_PERIOD` values. Not that only
+        [0 .. `TICKS_MAX`], inclusive, total `TICKS_PERIOD` values. Note that only
         non-negative values are used. For the most part, you should treat values
-        return by these functions as opaque. The only operations available for them
+        returned by these functions as opaque. The only operations available for them
         are ``ticks_diff()`` and ``ticks_add()`` functions described below.
 
-        Note: Performing standard mathematical operations (+, -) on these value
-        will lead to invalid result. Performing such operations and then passing
-        results as arguments to ``ticks_diff()`` or ``ticks_add()`` will also lead to
-        invalid result.
+        Note: Performing standard mathematical operations (+, -) or relational
+        operators (<, <=, >, >=) directly on these value will lead to invalid
+        result. Performing mathematical operations and then passing their results
+        as arguments to ``ticks_diff()`` or ``ticks_add()`` will also lead to
+        invalid results from the latter functions.
 
     .. function::  ticks_us()
 
@@ -114,7 +115,34 @@ Functions
    function is intended for very fine benchmarking or very tight real-time loops.
    Avoid using it in portable code.
 
-   Availability: Not every port implement this function.
+   Availability: Not every port implements this function.
+
+
+.. function::  ticks_add(ticks, delta)
+
+   Offset ticks value by a given number, which can be either positive or negative.
+   Given a ``ticks`` value, this function allows to calculate ticks value ``delta``
+   ticks before or after it, following modular-arithmetic definition of tick values
+   (see ``ticks_ms()`` above). ``ticks`` parameter must be a direct result of call
+   to ``tick_ms()``, ``ticks_us()``, ``ticks_cpu()`` functions (or from previous
+   call to ``ticks_add()``). However, ``delta`` can be an arbitrary integer number
+   or numeric expression. ``ticks_add()`` is useful for calculating deadlines for
+   events/tasks. (Note: you must use ``ticks_diff()`` function to work with
+   deadlines.)
+
+   Examples::
+
+        # Find out what ticks value there was 100ms ago
+        print(tick_add(time.ticks_ms(), -100))
+
+        # Calculate deadline for operation and test for it
+        deadline = tick_add(time.ticks_ms(), 200)
+        while ticks_diff(deadline, time.ticks_ms()) > 0:
+            do_a_little_of_something()
+
+        # Find out TICKS_MAX used by this port
+        print(tick_add(0, -1))
+
 
 .. function::  ticks_diff(ticks1, ticks2)
 
@@ -128,13 +156,21 @@ Functions
    **signed** value in the range [`-TICKS_PERIOD/2` .. `TICKS_PERIOD/2-1`] (that's a typical
    range definition for two's-complement signed binary integers). If the result is negative,
    it means that `ticks1` occured earlier in time than `ticks2`. Otherwise, it means that
-   `ticks1` was after `ticks2`. This holds `only` if `ticks1` and `ticks2` are apart from
+   `ticks1` occured after `ticks2`. This holds `only` if `ticks1` and `ticks2` are apart from
    each other for no more than `TICKS_PERIOD/2-1` ticks. If that does not hold, incorrect
    result will be returned. Specifically, if 2 tick values are apart for `TICKS_PERIOD/2-1`
    ticks, that value will be returned by the function. However, if `TICKS_PERIOD/2` of
    real-time ticks has passed between them, the function will return `-TICKS_PERIOD/2`
    instead, i.e. result value will wrap around to the negative range of possible values.
 
+   Informal rationale of the constraints above: Suppose you are locked in a room with no
+   means to monitor passing of time except a standard 12-notch clock. Then if you look at
+   dial-plate now, and don't look again for another 13 hours (e.g., if you fall for a
+   long sleep), then once you finally look again, it may seem to you that only 1 hour
+   has passed. To avoid this mistake, just look at the clock regularly. Your application
+   should do the same. "Too long sleep" metaphor also maps directly to application
+   behavior: don't let your application run any single task for too long. Run tasks
+   in steps, and do time-keeping inbetween.
 
    ``ticks_diff()`` is designed to accommodate various usage patterns, among them: