Merge #255

255: more monotonic timer docs r=nils-grepit a=japaric

covers

- initialization and configuration of the timer; this is now a responsibility of
  the application author
- correctness of `Monotonic::now()` in `#[init]`
- safety of `Monotonic::reset()`

closes #251
cc @jonas-schievink

(EDIT: yay, pull request number 0xFF)

Co-authored-by: Jorge Aparicio <jorge@japaric.io>

1 files changed, 12 insertions, 0 deletions

diff --git a/src/lib.rs b/src/lib.rs
index 959c9b7b..d661c54f 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -138,9 +138,21 @@ pub trait Monotonic {
     fn ratio() -> Fraction;
 
     /// Returns the current time
+    ///
+    /// # Correctness
+    ///
+    /// This function is *allowed* to return nonsensical values if called before `reset` is invoked
+    /// by the runtime. Therefore application authors should *not* call this function during the
+    /// `#[init]` phase.
     fn now() -> Self::Instant;
 
     /// Resets the counter to *zero*
+    ///
+    /// # Safety
+    ///
+    /// This function will be called *exactly once* by the RTFM runtime after `#[init]` returns and
+    /// before tasks can start; this is also the case in multi-core applications. User code must
+    /// *never* call this function.
     unsafe fn reset();
 
     /// A `Self::Instant` that represents a count of *zero*