Apply review suggestions.

src/binary_agreement/mod.rs

@@ -80,7 +80,7 @@ use threshold_sign;
 pub use self::binary_agreement::BinaryAgreement;
 pub use self::sbv_broadcast::Message as SbvMessage;
 
-/// An Binary Agreement error.
+/// A `BinaryAgreement` error.
 #[derive(Clone, Eq, PartialEq, Debug, Fail)]
 pub enum Error {
     /// Error handling a `ThresholdSign` message.
@@ -101,7 +101,7 @@ impl From<bincode::Error> for Error {
     }
 }
 
-/// An Binary Agreement result.
+/// A `BinaryAgreement` result.
 pub type Result<T> = ::std::result::Result<T, Error>;
 
 /// A `BinaryAgreement` step, containing at most one output.

src/broadcast/error.rs

@@ -29,7 +29,7 @@ pub enum Error {
     /// Failed to construct a Merkle tree proof.
     #[fail(display = "Proof construction failed")]
     ProofConstructionFailed,
-    /// Unknown sender
+    /// Unknown sender.
     #[fail(display = "Unknown sender")]
     UnknownSender,
 }

src/fault_log.rs

@@ -79,7 +79,7 @@ pub enum FaultKind {
 
 /// A structure representing the context of a faulty node. This structure
 /// describes which node is faulty (`node_id`) and which faulty behavior
-/// that the node exhibited ('kind').
+/// the node exhibited ('kind').
 #[derive(Debug, PartialEq)]
 pub struct Fault<N> {
     /// The faulty node's ID.

src/lib.rs

@@ -8,7 +8,7 @@
 //!
 //! A consensus algorithm is a protocol that helps a number of nodes agree on some data value.
 //! Byzantine fault tolerant systems can tolerate a number of faulty nodes _f_ (broken, or even
-//! controlled by an attacker), as long as the total number _N_ of nodes is greater than _3 f_.
+//! controlled by an attacker), as long as the total number of nodes _N_ is greater than _3 f_.
 //! Asynchronous protocols do not make assumptions about timing: Even if an adversary controls
 //! network scheduling and can delay message delivery, consensus will still be reached as long as
 //! all messages are _eventually_ delivered.
@@ -23,21 +23,15 @@
 //!
 //! ## Usage
 //!
-//! This crate is meant to be used as a component in a distributed application where the consensus
-//! problem arises. The application will usually run on different nodes, connected to each other
-//! via a network. The nodes give an input to the algorithm, exchange several messages, and
-//! eventually the algorithm returns an output, which is guaranteed to be the same in each correct
-//! node.
+//! `hbbft` is meant to solve the consensus problem in a distributed application. Participating
+//! nodes provide input to the algorithm and are guaranteed to eventually produce the same output,
+//! after passing several messages back and forth.
 //!
-//! However, the `hbbft` crate only implements the abstract protocols, not the networking. It is
-//! the application's responsibility to serialize, sign and send the messages to the other nodes.
-//! That is why in addition to methods for giving input, the algorithms also have a
-//! `handle_message` method. The application is required to call this for every (validly signed,
-//! deserialized) message that was received from a peer.
-//! The methods return a [Step](struct.Step.html) which may contain messages, fault logs and outputs.
-//! Messages are tagged with a peer they need to be sent to. A fault log is produced if a peer
-//! didn't follow the protocol, and therefore is now known to be faulty. The output is the result
-//! of the agreement, and guaranteed to be the same in all nodes.
+//! The crate only implements the abstract protocols, it is the application's responsibility to
+//! serialize, sign and send the messages. The application is required to call `handle_message` for
+//! every correctly signed message from a peer. Methods return a [Step](struct.Step.html) data
+//! structure, which contain messages that need to be sent, fault logs indicating misbehaving
+//! peers, and outputs.
 //!
 //! The network must contain a number of nodes that are known to each other by some unique
 //! identifiers (IDs), which is a generic type argument to the algorithms. Where applicable, the

src/messaging.rs

@@ -3,11 +3,11 @@
 pub struct SourcedMessage<M, N> {
     /// The ID of the sender.
     pub source: N,
-    /// The message's content.
+    /// The content of a message.
     pub message: M,
 }
 
-/// The destination of a message.
+/// The intended recipient(s) of a message.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum Target<N> {
     /// The message must be sent to all remote nodes.

src/sync_key_gen.rs

@@ -196,7 +196,7 @@ pub enum Error {
     /// Error generating keys.
     #[fail(display = "Error generating keys: {}", _0)]
     Generation(CryptoError),
-    /// Unknown sender
+    /// Unknown sender.
     #[fail(display = "Unknown sender")]
     UnknownSender,
     /// Failed to serialize message.

src/threshold_decrypt.rs

@@ -28,13 +28,13 @@ pub enum Error {
     /// Redundant input provided.
     #[fail(display = "Redundant input provided: {:?}", _0)]
     MultipleInputs(Box<Ciphertext>),
-    /// Invalid ciphertext
+    /// Invalid ciphertext.
     #[fail(display = "Invalid ciphertext: {:?}", _0)]
     InvalidCiphertext(Box<Ciphertext>),
-    /// Unknown sender
+    /// Unknown sender.
     #[fail(display = "Unknown sender")]
     UnknownSender,
-    /// Decryption failed
+    /// Decryption failed.
     #[fail(display = "Decryption failed: {:?}", _0)]
     Decryption(crypto::error::Error),
     /// Tried to decrypt before setting a cipherext.