Improve doc

Signed-off-by: Moritz Hoffmann <[email protected]>

Author: antiguru

container/src/lib.rs

@@ -126,9 +126,11 @@ pub trait ContainerBuilder: Default + 'static {
         container.clear();
     }
 
-    /// Indicates a good moment to release resources. By default, does nothing. Callers should
-    /// not rely on this method releasing any internal state though, i.e., the caller first
-    /// needs to drain the contents using [`Self::finish`].
+    /// Indicates a good moment to release resources.
+    ///
+    /// By default, does nothing. Callers first needs to drain the contents using [`Self::finish`]
+    /// before calling this function. The implementation should not change the contents of the
+    /// builder.
     #[inline]
     fn relax(&mut self) { }
 }

timely/examples/columnar.rs

@@ -335,8 +335,8 @@ mod builder {
 
         #[inline]
         fn relax(&mut self) {
-            /// The caller is responsible for draining all contents; assert that we are empty.
-            /// The assertion is not strictly necessary, but it helps catch bugs.
+            // The caller is responsible for draining all contents; assert that we are empty.
+            // The assertion is not strictly necessary, but it helps catch bugs.
             assert!(self.current.is_empty());
             assert!(self.pending.is_empty());
             *self = Self::default();