Include advice on how to handle Step in docs. (#297)

* Fixed spelling mistake in `Step` docs.
* Added suggestion on how to handle `Step` output.

src/traits.rs

@@ -10,7 +10,7 @@ use serde::Serialize;
 use fault_log::{Fault, FaultLog};
 use TargetedMessage;
 
-/// A transaction, user message, etc.
+/// A transaction, user message, or other user data.
 pub trait Contribution: Eq + Debug + Hash + Send + Sync {}
 impl<C> Contribution for C where C: Eq + Debug + Hash + Send + Sync {}
 
@@ -26,8 +26,28 @@ impl<M> Message for M where M: Debug + Send + Sync {}
 pub trait SessionIdT: Display + Serialize + Send + Sync + Clone {}
 impl<S> SessionIdT for S where S: Display + Serialize + Send + Sync + Clone {}
 
-/// Result of one step of the local state machine of a distributed algorithm. Such a result should
-/// be used and never discarded by the client of the algorithm.
+/// Single algorithm step outcome.
+///
+/// Each time input (typically in the form of user input or incoming network messages) is provided
+/// to an instance of an algorithm, a `Step` is produced, potentially containing output values,
+/// a fault log, and network messages.
+///
+/// Any `Step` **must always be used** by the client application; at the very least the resulting
+/// messages must be queued.
+///
+/// ## Handling unused Steps
+///
+/// In the (rare) case of a `Step` not being of any interest at all, instead of discarding it
+/// through `let _ = ...` or similar constructs, the implicit assumption should explicitly be
+/// checked instead:
+///
+/// ```ignore
+/// assert!(alg.propose(123).expect("Could not propose value").is_empty(),
+///         "Algorithm will never output anything on first proposal");
+/// ```
+///
+/// If an edge case occurs and outgoing messages are generated as a result, the `assert!` will
+/// catch it, instead of potentially stalling the algorithm.
 #[must_use = "The algorithm step result must be used."]
 #[derive(Debug)]
 pub struct Step<D>
@@ -130,7 +150,7 @@ where
         }
     }
 
-    /// Returns `true` if there are now messages, faults or outputs.
+    /// Returns `true` if there are no messages, faults or outputs.
     pub fn is_empty(&self) -> bool {
         self.output.is_empty() && self.fault_log.is_empty() && self.messages.is_empty()
     }