From b04103f6df712233b7659f2a845461f4db682e32 Mon Sep 17 00:00:00 2001
From: Jorge Aparicio <jorge@japaric.io>
Date: Tue, 21 Jan 2020 22:23:20 +0100
Subject: [PATCH] docs: do not use Instant::now in #[init]

---
 examples/schedule.rs | 1 +
 src/cyccnt.rs        | 4 ++++
 2 files changed, 5 insertions(+)

diff --git a/examples/schedule.rs b/examples/schedule.rs
index 97818e36a1..a1c41ca574 100644
--- a/examples/schedule.rs
+++ b/examples/schedule.rs
@@ -20,6 +20,7 @@ const APP: () = {
         cx.core.DWT.enable_cycle_counter();
 
         // semantically, the monotonic timer is frozen at time "zero" during `init`
+        // NOTE do *not* call `Instant::now` in this context; it will return a nonsense value
         let now = cx.start; // the start time of the system
 
         hprintln!("init @ {:?}", now).unwrap();
diff --git a/src/cyccnt.rs b/src/cyccnt.rs
index 86969cb1a3..4b12408724 100644
--- a/src/cyccnt.rs
+++ b/src/cyccnt.rs
@@ -30,6 +30,10 @@ pub struct Instant {
 
 impl Instant {
     /// Returns an instant corresponding to "now"
+    ///
+    /// *HEADS UP* this function can, and will, return nonsensical values if called within `init`.
+    /// Only use it in `idle` and tasks. In `init`, use the `init::Context.start` field, or the
+    /// `CYCCNT::zero` function, instead of this function
     pub fn now() -> Self {
         Instant {
             inner: DWT::get_cycle_count() as i32,