Add readme for embassy-time

2 files changed, 44 insertions, 42 deletions

diff --git a/embassy-time/README.md b/embassy-time/README.md
new file mode 100644
index 000000000..2be80ff9c
--- /dev/null
+++ b/embassy-time/README.md
@@ -0,0 +1,43 @@
+# embassy-time
+
+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.
+
+Tick counts are 64 bits. At the highest supported tick rate of 1Mhz this 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.
+
+[`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
+
+[`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
+
+The `time` module deals exclusively with a monotonically increasing tick count.
+Therefore it has no direct support for wall-clock time ("real life" datetimes
+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.
diff --git a/embassy-time/src/lib.rs b/embassy-time/src/lib.rs
index a6454d55e..a6c5d78cc 100644
--- a/embassy-time/src/lib.rs
+++ b/embassy-time/src/lib.rs
@@ -1,50 +1,9 @@
 #![cfg_attr(not(any(feature = "std", feature = "wasm")), no_std)]
 #![cfg_attr(feature = "nightly", feature(generic_associated_types, type_alias_impl_trait))]
+#![doc = include_str!("../README.md")]
 #![allow(clippy::new_without_default)]
 #![warn(missing_docs)]
 
-//! 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.
-//!
-//! Tick counts are 64 bits. At the highest supported tick rate of 1Mhz this 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.
-//!
-//! [`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
-//!
-//! [`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
-//!
-//! The `time` module deals exclusively with a monotonically increasing tick count.
-//! Therefore it has no direct support for wall-clock time ("real life" datetimes
-//! 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.
-
 // This mod MUST go first, so that the others see its macros.
 pub(crate) mod fmt;