add docs

Author: pvdrz

src/machine.rs

@@ -293,7 +293,7 @@ pub struct Evaluator<'mir, 'tcx> {
     /// The table of directory descriptors.
     pub(crate) dir_handler: shims::unix::DirHandler,
 
-    /// FIXME: docs
+    /// This machine's monotone clock.
     pub(crate) clock: Clock,
 
     /// The set of threads.

src/shims/time.rs

@@ -8,10 +8,11 @@ use crate::*;
 
 const NANOSECOND_PER_BASIC_BLOCK: u64 = 10;
 
+/// A monotone clock used for `Instant` simulation.
 #[derive(Debug)]
 pub enum Clock {
     Host {
-        /// The "time anchor" for this machine's monotone clock (for `Instant` simulation).
+        /// The "time anchor" for this machine's monotone clock.
         time_anchor: Instant,
     },
     Virtual {
@@ -21,6 +22,7 @@ pub enum Clock {
 }
 
 impl Clock {
+    /// Create a new clock based on the availability of communication with the host.
     pub fn new(communicate: bool) -> Self {
         if communicate {
             Self::Host { time_anchor: Instant::now() }
@@ -29,6 +31,7 @@ impl Clock {
         }
     }
 
+    /// Get the current time relative to this clock.
     pub fn get(&self) -> Duration {
         match self {
             Self::Host { time_anchor } => Instant::now().saturating_duration_since(*time_anchor),
@@ -37,6 +40,7 @@ impl Clock {
         }
     }
 
+    /// Let the time pass for a small interval.
     pub fn tick(&self) {
         match self {
             Self::Host { .. } => {
@@ -48,6 +52,7 @@ impl Clock {
         }
     }
 
+    /// Sleep for the desired duration.
     pub fn sleep(&self, duration: Duration) {
         match self {
             Self::Host { .. } => std::thread::sleep(duration),
@@ -58,7 +63,7 @@ impl Clock {
         }
     }
 
-
+    /// Compute `now + duration` relative to this clock.
     pub fn checked_add_since_now(&self, duration: Duration) -> Option<Time> {
         match self {
             Self::Host { .. } => Instant::now().checked_add(duration).map(Time::Monotonic),
@@ -70,6 +75,8 @@ impl Clock {
         }
     }
 
+    /// Compute `start + duration` relative to this clock where `start` is the instant of time when
+    /// this clock was created.
     pub fn checked_add_since_start(&self, duration: Duration) -> Option<Time> {
         match self {
             Self::Host { time_anchor } => time_anchor.checked_add(duration).map(Time::Monotonic),
@@ -78,6 +85,7 @@ impl Clock {
         }
     }
 
+    /// Assert that this clock is a virtual one and get the current time in nanoseconds.
     pub(crate) fn assert_virtual(&self) -> &AtomicU64 {
         match self {
             Clock::Host { .. } => panic!(),