Improved documentation

* Documented features including all tick rates
* Corrected some out-of-date information
* Sorted tick rate features
* Removed gen_tick.py dependency on toml
* Restructured README.md to better explain tick rate, more
  clearly prioritise time driver docs, correct header levels

1 files changed, 20 insertions, 16 deletions

diff --git a/embassy-time/README.md b/embassy-time/README.md
index 2be80ff9c..a4a622700 100644
--- a/embassy-time/README.md
+++ b/embassy-time/README.md
@@ -3,25 +3,40 @@
 Timekeeping, delays and timeouts.
 
 Timekeeping is done with elapsed time since system boot. Time is represented in
-ticks, where the tick rate is defined by the current driver, usually to match
-the tick rate of the hardware.
+ticks, where the tick rate is defined either by the driver (in the case of a fixed-
+rate tick) or chosen by the user with a [tick rate](#tick-rate) feature. The chosen
+tick rate applies to everything in `embassy-time` and thus determines the maximum 
+timing resolution of <code>(1 / tick_rate) seconds</code>.
 
-Tick counts are 64 bits. At the highest supported tick rate of 1Mhz this supports
+Tick counts are 64 bits. The default tick rate of 1Mhz supports
 representing time spans of up to ~584558 years, which is big enough for all practical
 purposes and allows not having to worry about overflows.
 
+## Time driver
+
+The `time` module is backed by a global "time driver" specified at build time.
+Only one driver can be active in a program.
+
+All methods and structs transparently call into the active driver. This makes it
+possible for libraries to use `embassy_time` in a driver-agnostic way without
+requiring generic parameters.
+
+For more details, check the [`driver`] module.
+
+## Instants and Durations
+
 [`Instant`] represents a given instant of time (relative to system boot), and [`Duration`]
 represents the duration of a span of time. They implement the math operations you'd expect,
 like addition and substraction.
 
-# Delays and timeouts
+## Delays and timeouts
 
 [`Timer`] allows performing async delays. [`Ticker`] allows periodic delays without drifting over time.
 
 An implementation of the `embedded-hal` delay traits is provided by [`Delay`], for compatibility
 with libraries from the ecosystem.
 
-# Wall-clock time
+## Wall-clock time
 
 The `time` module deals exclusively with a monotonically increasing tick count.
 Therefore it has no direct support for wall-clock time ("real life" datetimes
@@ -30,14 +45,3 @@ like `2021-08-24 13:33:21`).
 If persistence across reboots is not needed, support can be built on top of
 `embassy_time` by storing the offset between "seconds elapsed since boot"
 and "seconds since unix epoch".
-
-# Time driver
-
-The `time` module is backed by a global "time driver" specified at build time.
-Only one driver can be active in a program.
-
-All methods and structs transparently call into the active driver. This makes it
-possible for libraries to use `embassy_time` in a driver-agnostic way without
-requiring generic parameters.
-
-For more details, check the [`driver`] module.