Doc

Author: jedisct1

README.md

@@ -22,6 +22,6 @@ let stop = p.now();
 let elapsed2 = stop - start;
 
 let elapsed_total = elapsed1 + elapsed2;
-let elapsed_total_secs = elapsed_total_as_secs_f64();
+let elapsed_total_secs = elapsed_total.as_secs_f64(&p);
 let hw_ticks = elapsed_total.ticks();
 ```

src/config.rs

@@ -14,6 +14,8 @@ impl Default for Config {
 }
 
 impl Config {
+    /// Sets the duration of the calibration, required to estimate the frequency
+    /// of the hardware counter on Linux. Default is 5 seconds.
     pub fn setup_duration(mut self, setup_duration: Duration) -> Self {
         self.setup_duration = setup_duration;
         self

src/lib.rs

@@ -1,5 +1,28 @@
 #![cfg_attr(asm, feature(asm))]
 
+/// Precision is a simple crate to perform measurements using hardware counters.
+///
+/// It is especially useful for performing micro-benchmarks.
+///
+/// Example
+/// ```rust
+/// extern crate precision;
+///
+/// let p = precision::Precision::new(precision::Config::default()).unwrap();
+///
+/// let start = p.now();
+///
+/// let stop = p.now();
+/// let elapsed1 = stop - start;
+///
+/// let start = p.now();
+/// let stop = p.now();
+/// let elapsed2 = stop - start;
+///
+/// let elapsed_total = elapsed1 + elapsed2;
+/// let elapsed_total_secs = elapsed_total.as_secs_f64(&p);
+/// let hw_ticks = elapsed_total.ticks();
+/// ```
 extern crate libc;
 
 mod config;

src/precision.rs

@@ -10,11 +10,15 @@ pub struct Precision {
 }
 
 impl Precision {
+    /// Initialize the crate. Note that on Linux system, this will
+    /// perform calibration before returning. You may want to do this
+    /// only twice. The `Precision` value can then be cloned if needed.
     pub fn new(config: Config) -> Result<Self, &'static str> {
         let frequency = Precision::guess_frequency(&config)?;
         Ok(Precision { frequency })
     }
 
+    /// Returns the current timestamp
     #[inline]
     pub fn now(&self) -> Timestamp {
         CPUCounter::current()

src/timestamp.rs

@@ -1,9 +1,11 @@
 use super::precision::*;
 use std::ops::*;
 
+/// A timestamp. Note that this is an opaque structure.
 #[derive(Clone, Copy, Eq, PartialEq)]
 pub struct Timestamp(pub(crate) u64);
 
+/// The difference between two timestamps.
 #[derive(Clone, Copy, Eq, PartialEq, Ord, PartialOrd)]
 pub struct Elapsed(u64);
 
@@ -37,36 +39,43 @@ impl AddAssign for Elapsed {
 }
 
 impl Elapsed {
+    /// Returns a nul duration
     #[inline]
     pub fn new() -> Self {
         Elapsed(0)
     }
 
+    /// Builds a `Duration` from a number of ticks
     #[inline]
     pub fn from_ticks(ticks: u64) -> Self {
         Elapsed(ticks)
     }
 
+    /// Returns the number of ticks for the given duration
     #[inline]
     pub fn ticks(&self) -> u64 {
         self.0
     }
 
+    /// Returns the duration as a number of seconds
     #[inline]
     pub fn as_secs(&self, precision: &Precision) -> u64 {
         self.0 / precision.frequency
     }
 
+    /// Returns the duration as a number of seconds (floating-point)
     #[inline]
     pub fn as_secs_f64(&self, precision: &Precision) -> f64 {
         self.0 as f64 / precision.frequency as f64
     }
 
+    /// Returns the duration as milliseconds
     #[inline]
     pub fn as_millis(&self, precision: &Precision) -> u64 {
         self.0 * 1_000 / precision.frequency
     }
 
+    /// Returns the duration as nanoseconds
     #[inline]
     pub fn as_ns(&self, precision: &Precision) -> u64 {
         (((self.0 as f64 * 1_000.0) / precision.frequency as f64) * 1_000_000.0) as u64