Document various trait invariants

Author: bkirwi

timely/src/order.rs

@@ -5,6 +5,9 @@
 /// This trait is distinct from Rust's `PartialOrd` trait, because the implementation
 /// of that trait precludes a distinct `Ord` implementation. We need an independent
 /// trait if we want to have a partially ordered type that can also be sorted.
+///
+/// The partial order should be consistent with [Eq], in the sense that if `a == b` then
+/// `a.less_equal(b)` and `b.less_equal(a)`.
 pub trait PartialOrder : Eq {
     /// Returns true iff one element is strictly less than the other.
     fn less_than(&self, other: &Self) -> bool {

timely/src/progress/timestamp.rs

@@ -9,10 +9,13 @@ use crate::communication::Data;
 use crate::order::PartialOrder;
 
 /// A composite trait for types that serve as timestamps in timely dataflow.
+///
+/// By implementing this trait, you promise that the type's [PartialOrder] implementation
+/// is compatible with [Ord], such that if `a.less_equal(b)` then `a <= b`.
 pub trait Timestamp: Clone+Eq+PartialOrder+Debug+Send+Any+Data+Hash+Ord {
     /// A type summarizing action on a timestamp along a dataflow path.
     type Summary : PathSummary<Self> + 'static;
-    /// A minimum value suitable as a default.
+    /// A unique minimum value in our partial order, suitable as a default.
     fn minimum() -> Self;
 }
 
@@ -28,14 +31,17 @@ pub trait PathSummary<T> : Clone+'static+Eq+PartialOrder+Debug+Default {
     /// in computation, uses this method and will drop messages with timestamps that when advanced
     /// result in `None`. Ideally, all other timestamp manipulation should behave similarly.
     ///
+    /// Note that `Self::default()` is expected to behave as an "empty" or "noop" summary, such that
+    /// `Self::default().results_in(&t) == Some(t)`.
+    ///
     /// # Examples
     /// ```
     /// use timely::progress::timestamp::PathSummary;
     ///
     /// let timestamp = 3;
     ///
     /// let summary1 = 5;
-    /// let summary2 = usize::max_value() - 2;
+    /// let summary2 = usize::MAX - 2;
     ///
     /// assert_eq!(summary1.results_in(&timestamp), Some(8));
     /// assert_eq!(summary2.results_in(&timestamp), None);
@@ -45,18 +51,31 @@ pub trait PathSummary<T> : Clone+'static+Eq+PartialOrder+Debug+Default {
     ///
     /// It is possible that the two composed paths result in an invalid summary, for example when
     /// integer additions overflow. If it is correct that all timestamps moved along these paths
-    /// would also result in overflow and be discarded, `followed_by` can return `None. It is very
+    /// would also result in overflow and be discarded, `followed_by` can return `None`. It is very
     /// important that this not be used casually, as this does not prevent the actual movement of
     /// data.
     ///
+    /// Calling `results_in` on the composed summary should behave the same as though the two
+    /// summaries were applied to the argument in order.
+    ///
     /// # Examples
     /// ```
     /// use timely::progress::timestamp::PathSummary;
     ///
     /// let summary1 = 5;
-    /// let summary2 = usize::max_value() - 3;
+    /// let summary2 = usize::MAX - 3;
     ///
     /// assert_eq!(summary1.followed_by(&summary2), None);
+    ///
+    /// let time = 10;
+    /// let summary2 = 15;
+    /// assert_eq!(
+    ///     // Applying the composed summary...
+    ///     summary1.followed_by(&summary2).and_then(|s| s.results_in(&time)),
+    ///     // ...has the same result as applying the two summaries in sequence.
+    ///     summary1.results_in(&time).and_then(|t| summary2.results_in(&t)),
+    /// );
+    ///
     /// ```
     fn followed_by(&self, other: &Self) -> Option<Self>;
 }