utime module documentation fixes and cleanup:

SpotlightKid · pfalcon · commit 9b80a1e3e93e · 2017-03-17T20:45:08.000+03:00
* Fix mis-spelling of `ticks_add` in code examples.
* Be consistent about parentheses after function names.
* Be consistent about formatting of function, variable and constant names.
* Be consistent about spaces and punctuation.
* Fix some language errors (missing or wrong words, wrong word order).
* Keep line length under 90 chars.

Signed-off-by: Christopher Arndt &lt;chris@chrisarndt.de&gt;
diff --git a/docs/library/utime.rst b/docs/library/utime.rst
@@ -58,7 +58,7 @@ Functions
 .. only:: port_unix or port_pyboard or port_esp8266
 
     .. function:: sleep(seconds)
-    
+
        Sleep for the given number of seconds.  Seconds can be a floating-point number to
        sleep for a fractional number of seconds. Note that other MicroPython ports may
        not accept floating-point argument, for compatibility with them use ``sleep_ms()``
@@ -67,48 +67,48 @@ Functions
 .. only:: port_wipy
 
     .. function:: sleep(seconds)
-    
+
        Sleep for the given number of seconds.
 
 .. only:: port_unix or port_pyboard or port_wipy or port_esp8266
 
-    .. function::  sleep_ms(ms)
+    .. function:: sleep_ms(ms)
 
        Delay for given number of milliseconds, should be positive or 0.
 
-    .. function::  sleep_us(us)
+    .. function:: sleep_us(us)
 
-       Delay for given number of microseconds, should be positive or 0
+       Delay for given number of microseconds, should be positive or 0.
 
-    .. function::  ticks_ms()
+    .. function:: ticks_ms()
 
-        Returns an increasing millisecond counter with an arbitrary reference point,
-        that wraps around after some value. This value is not explicitly exposed,
-        but we will refer to it as `TICKS_MAX` to simplify discussion. Period of
-        the values is `TICKS_PERIOD = TICKS_MAX + 1`. `TICKS_PERIOD` is guaranteed
-        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. Note that only
-        non-negative values are used. For the most part, you should treat values
-        returned by these functions as opaque. The only operations available for them
-        are ``ticks_diff()`` and ``ticks_add()`` functions described below.
+        Returns an increasing millisecond counter with an arbitrary reference point, that
+        wraps around after some value. This value is not explicitly exposed, but we will
+        refer to it as ``TICKS_MAX`` to simplify discussion. Period of the values is
+        ``TICKS_PERIOD = TICKS_MAX + 1``. ``TICKS_PERIOD`` is guaranteed 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. Note that only
+        non-negative values are used. For the most part, you should treat values 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 (+, -) 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()
+    .. function:: ticks_us()
 
-       Just like ``ticks_ms`` above, but in microseconds.
+       Just like ``ticks_ms()`` above, but in microseconds.
 
-.. function::  ticks_cpu()
+.. function:: ticks_cpu()
 
-   Similar to ``ticks_ms`` and ``ticks_us``, but with the highest possible resolution
+   Similar to ``ticks_ms()`` and ``ticks_us()``, but with the highest possible resolution
    in the system. This is usually CPU clocks, and that's why the function is named that
-   way. But it doesn't have to a CPU clock, some other timing source available in a
+   way. But it doesn't have to be a CPU clock, some other timing source available in a
    system (e.g. high-resolution timer) can be used instead. The exact timing unit
    (resolution) of this function is not specified on ``utime`` module level, but
    documentation for a specific port may provide more specific information. This
@@ -118,13 +118,13 @@ Functions
    Availability: Not every port implements this function.
 
 
-.. function::  ticks_add(ticks, delta)
+.. 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
+   to ``ticks_ms()``, ``ticks_us()``, or ``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
@@ -133,35 +133,37 @@ Functions
    Examples::
 
         # Find out what ticks value there was 100ms ago
-        print(tick_add(time.ticks_ms(), -100))
+        print(ticks_add(time.ticks_ms(), -100))
 
         # Calculate deadline for operation and test for it
-        deadline = tick_add(time.ticks_ms(), 200)
+        deadline = ticks_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)
-
-   Measure ticks difference between values returned from ticks_ms(), ticks_us(), or ticks_cpu()
-   functions. The argument order is the same as for subtraction operator,
-   ``tick_diff(ticks1, ticks2)`` has the same meaning as ``ticks1 - ticks2``. However, values returned by
-   ticks_ms(), etc. functions may wrap around, so directly using subtraction on them will
-   produce incorrect result. That is why ticks_diff() is needed, it implements modular
-   (or more specifically, ring) arithmetics to produce correct result even for wrap-around
-   values (as long as they not too distant inbetween, see below). The function returns
-   **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` 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.
+        print(ticks_add(0, -1))
+
+
+.. function:: ticks_diff(ticks1, ticks2)
+
+   Measure ticks difference between values returned from ``ticks_ms()``, ``ticks_us()``,
+   or ``ticks_cpu()`` functions. The argument order is the same as for subtraction
+   operator, ``ticks_diff(ticks1, ticks2)`` has the same meaning as ``ticks1 - ticks2``.
+   However, values returned by ``ticks_ms()``, etc. functions may wrap around, so
+   directly using subtraction on them will produce incorrect result. That is why
+   ``ticks_diff()`` is needed, it implements modular (or more specifically, ring)
+   arithmetics to produce correct result even for wrap-around values (as long as they not
+   too distant inbetween, see below). The function returns **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`` 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 two 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
@@ -200,20 +202,21 @@ Functions
             print("Oops, running late, tell task to run faster!")
             task.run(run_faster=true)
 
-   Note: Do not pass ``time()`` values to ``ticks_diff()``, and should use
+   Note: Do not pass ``time()`` values to ``ticks_diff()``, you should use
    normal mathematical operations on them. But note that ``time()`` may (and will)
    also overflow. This is known as https://en.wikipedia.org/wiki/Year_2038_problem .
 
 
 .. function:: time()
 
-   Returns the number of seconds, as an integer, since the Epoch, assuming that underlying
-   RTC is set and maintained as described above. If an RTC is not set, this function returns
-   number of seconds since a port-specific reference point in time (for embedded boards without
-   a battery-backed RTC, usually since power up or reset). If you want to develop portable
-   MicroPython application, you should not rely on this function to provide higher than second
-   precision. If you need higher precision, use ``ticks_ms()`` and ``ticks_us()`` functions,
-   if you need calendar time, ``localtime()`` without an argument is a better choice.
+   Returns the number of seconds, as an integer, since the Epoch, assuming that
+   underlying RTC is set and maintained as described above. If an RTC is not set, this
+   function returns number of seconds since a port-specific reference point in time (for
+   embedded boards without a battery-backed RTC, usually since power up or reset). If you
+   want to develop portable MicroPython application, you should not rely on this function
+   to provide higher than second precision. If you need higher precision, use
+   ``ticks_ms()`` and ``ticks_us()`` functions, if you need calendar time,
+   ``localtime()`` without an argument is a better choice.
 
    .. admonition:: Difference to CPython
       :class: attention
