Better enum names and docs

Author: Marshall Pierce

src/lib.rs

@@ -243,15 +243,25 @@ pub struct Histogram<T: Counter> {
 /// Errors that can occur when creating a histogram.
 #[derive(Debug, Eq, PartialEq, Clone, Copy)]
 pub enum CreationError {
-    /// Lowest discernible value must be >= 1
-    LowTooSmall,
-    /// Lowest discernible value must be <= u64::max_value() / 2
-    LowTooBig,
-    /// Highest trackable value must be >= 2 * lowest discernible value
+    /// Lowest discernible value must be >= 1.
+    LowIsZero,
+    /// Lowest discernible value must be <= `u64::max_value() / 2` because the highest value is
+    /// a `u64` and the lowest value must be no bigger than half the highest.
+    LowExceedsMax,
+    /// Highest trackable value must be >= 2 * lowest discernible value for some internal
+    /// calculations to work out. In practice, high is typically much higher than 2 * low.
     HighLessThanTwiceLow,
-    /// Number of significant digits must be between 0 and 5
-    SigFigTooBig,
-    /// Cannot represent sigfig worth of values beyond low
+    /// Number of significant digits must be in the range `[0, 5]`. It is capped at 5 because 5
+    /// significant digits is already more than almost anyone needs, and memory usage scales
+    /// exponentially as this increases.
+    SigFigExceedsMax,
+    /// Cannot represent sigfig worth of values beyond the lowest discernible value. Decrease the
+    /// significant figures, lowest discernible value, or both.
+    ///
+    /// This could happen if low is very large (like 2^60) and sigfigs is 5, which requires 18
+    /// additional bits, which would then require more bits than will fit in a u64. Specifically,
+    /// the exponent of the largest power of two that is smaller than the lowest value and the bits
+    /// needed to represent the requested significant figures must sum to 63 or less.
     CannotRepresentSigFigBeyondLow
 }
 
@@ -586,9 +596,9 @@ impl<T: Counter> Histogram<T> {
     /// auto-adjusting highest trackable value. Can auto-resize up to track values up to
     /// `(i64::max_value() / 2)`.
     ///
-    /// `sigfig` specifies the number of significant value digits to preserve in the recorded data.
-    /// This is the number of significant decimal digits to which the histogram will maintain value
-    /// resolution and separation. Must be a non-negative integer between 0 and 5.
+    /// See [`new_with_bounds`] for info on `sigfig`.
+    ///
+    /// [`new_with_bounds`]: #method.new_with_bounds
     pub fn new(sigfig: u8) -> Result<Histogram<T>, CreationError> {
         let mut h = Self::new_with_bounds(1, 2, sigfig);
         if let Ok(ref mut h) = h {
@@ -601,41 +611,45 @@ impl<T: Counter> Histogram<T> {
     /// significant decimal digits. The histogram will be constructed to implicitly track
     /// (distinguish from 0) values as low as 1. Auto-resizing will be disabled.
     ///
-    /// `high` is the highest value to be tracked by the histogram, and must be a positive integer
-    /// that is >= 2. `sigfig` specifies the number of significant figures to maintain. This is the
-    /// number of significant decimal digits to which the histogram will maintain value resolution
-    /// and separation. Must be a non-negative integer between 0 and 5.
+    /// See [`new_with_bounds`] for info on `high` and `sigfig`.
+    ///
+    /// [`new_with_bounds`]: #method.new_with_bounds
     pub fn new_with_max(high: u64, sigfig: u8) -> Result<Histogram<T>, CreationError> {
         Self::new_with_bounds(1, high, sigfig)
     }
 
     /// Construct a `Histogram` with known upper and lower bounds for recorded sample values.
-    /// Providing a lowest discernible value (`low`) is useful is situations where the units used
-    /// for the histogram's values are much smaller that the minimal accuracy required. E.g. when
-    /// tracking time values stated in nanosecond units, where the minimal accuracy required is a
-    /// microsecond, the proper value for `low` would be 1000.
     ///
     /// `low` is the lowest value that can be discerned (distinguished from 0) by the histogram,
     /// and must be a positive integer that is >= 1. It may be internally rounded down to nearest
-    /// power of 2. `high` is the highest value to be tracked by the histogram, and must be a
-    /// positive integer that is `>= (2 * low)`. `sigfig` Specifies the number of significant
-    /// figures to maintain. This is the number of significant decimal digits to which the
-    /// histogram will maintain value resolution and separation. Must be a non-negative integer
-    /// between 0 and 5.
+    /// power of 2. Providing a lowest discernible value (`low`) is useful is situations where the
+    /// units used for the histogram's values are much smaller that the minimal accuracy required.
+    /// E.g. when tracking time values stated in nanosecond units, where the minimal accuracy
+    /// required is a microsecond, the proper value for `low` would be 1000. If you're not sure,
+    /// use 1.
+    ///
+    /// `high` is the highest value to be tracked by the histogram, and must be a
+    /// positive integer that is `>= (2 * low)`. If you're not sure, use `u64::max_value()`.
+    ///
+    /// `sigfig` Specifies the number of significant figures to maintain. This is the number of
+    /// significant decimal digits to which the histogram will maintain value resolution and
+    /// separation. Must be in the range [0, 5]. If you're not sure, use 3. As `sigfig` increases,
+    /// memory usage grows exponentially, so choose carefully if there will be many histograms in
+    /// memory at once or if storage is otherwise a concern.
     pub fn new_with_bounds(low: u64, high: u64, sigfig: u8) -> Result<Histogram<T>, CreationError> {
         // Verify argument validity
         if low < 1 {
-            return Err(CreationError::LowTooSmall);
+            return Err(CreationError::LowIsZero);
         }
         if low > u64::max_value() / 2 {
             // avoid overflow in 2 * low
-            return Err(CreationError::LowTooBig)
+            return Err(CreationError::LowExceedsMax)
         }
         if high < 2 * low {
             return Err(CreationError::HighLessThanTwiceLow);
         }
         if sigfig > 5 {
-            return Err(CreationError::SigFigTooBig);
+            return Err(CreationError::SigFigExceedsMax);
         }
 
         // Given a 3 decimal point accuracy, the expectation is obviously for "+/- 1 unit at 1000".