Document the collection invariant (#384)

* Document the collection invariant

* must_use on the lattice operations

Author: bkirwi

differential-dataflow/src/collection.rs

@@ -44,6 +44,10 @@ pub struct Collection<G: Scope, D, R = isize, C = Vec<(D, <G as ScopeParent>::Ti
     ///
     /// This field is exposed to support direct timely dataflow manipulation when required, but it is
     /// not intended to be the idiomatic way to work with the collection.
+    ///
+    /// The timestamp in the data is required to always be at least the timestamp _of_ the data, in
+    /// the timely-dataflow sense. If this invariant is not upheld, differential operators may behave
+    /// unexpectedly.
     pub inner: timely::dataflow::StreamCore<G, C>,
     /// Phantom data for unreferenced `D` and `R` types.
     phantom: std::marker::PhantomData<(D, R)>,
@@ -56,6 +60,9 @@ impl<G: Scope, D, R, C> Collection<G, D, R, C> {
     /// idiomatic approach to convert timely streams to collections. Also, the `input::Input` trait
     /// provides a `new_collection` method which will create a new collection for you without exposing
     /// the underlying timely stream at all.
+    ///
+    /// This stream should satisfy the timestamp invariant as documented on [Collection]; this
+    /// method does not check it.
     pub fn new(stream: StreamCore<G, C>) -> Collection<G, D, R, C> {
         Collection { inner: stream, phantom: std::marker::PhantomData }
     }
@@ -433,8 +440,9 @@ impl<G: Scope, D: Clone+'static, R: Clone+'static> Collection<G, D, R> {
     ///
     /// It is assumed that `func` only advances timestamps; this is not verified, and things may go horribly
     /// wrong if that assumption is incorrect. It is also critical that `func` be monotonic: if two times are
-    /// ordered, they should have the same order once `func` is applied to them (this is because we advance the
-    /// timely capability with the same logic, and it must remain `less_equal` to all of the data timestamps).
+    /// ordered, they should have the same order or compare equal once `func` is applied to them (this
+    /// is because we advance the timely capability with the same logic, and it must remain `less_equal`
+    /// to all of the data timestamps).
     pub fn delay<F>(&self, func: F) -> Collection<G, D, R>
     where F: FnMut(&G::Timestamp) -> G::Timestamp + Clone + 'static {
 
@@ -446,6 +454,7 @@ impl<G: Scope, D: Clone+'static, R: Clone+'static> Collection<G, D, R> {
             .map_in_place(move |x| x.1 = func2(&x.1))
             .as_collection()
     }
+
     /// Applies a supplied function to each update.
     ///
     /// This method is most commonly used to report information back to the user, often for debugging purposes.
@@ -622,6 +631,10 @@ pub trait AsCollection<G: Scope, D, R, C> {
 }
 
 impl<G: Scope, D, R, C: Clone> AsCollection<G, D, R, C> for StreamCore<G, C> {
+    /// Converts the type to a differential dataflow collection.
+    ///
+    /// By calling this method, you guarantee that the timestamp invariant (as documented on
+    /// [Collection]) is upheld. This method will not check it.
     fn as_collection(&self) -> Collection<G, D, R, C> {
         Collection::<G,D,R,C>::new(self.clone())
     }

differential-dataflow/src/lattice.rs

@@ -27,6 +27,7 @@ pub trait Lattice : PartialOrder {
     /// assert_eq!(join, Product::new(4, 7));
     /// # }
     /// ```
+    #[must_use]
     fn join(&self, other: &Self) -> Self;
 
     /// Updates `self` to the smallest element greater than or equal to both arguments.
@@ -67,6 +68,7 @@ pub trait Lattice : PartialOrder {
     /// assert_eq!(meet, Product::new(3, 6));
     /// # }
     /// ```
+    #[must_use]
     fn meet(&self, other: &Self) -> Self;
 
     /// Updates `self` to the largest element less than or equal to both arguments.