From 97e772e87a88bea5cb8757f86b03c7bcb45dc3e7 Mon Sep 17 00:00:00 2001
From: Anatoly Yakovenko <aeyakovenko@gmail.com>
Date: Tue, 17 Apr 2018 19:46:50 -0700
Subject: [PATCH] docs

---
 src/packet.rs      |  1 +
 src/streamer.rs    | 15 ++++++++++-----
 src/subscribers.rs | 12 +++++++-----
 3 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/src/packet.rs b/src/packet.rs
index 72e5cf8a4..2106bf5da 100644
--- a/src/packet.rs
+++ b/src/packet.rs
@@ -1,3 +1,4 @@
+//! The `packet` module defines data structures and methods to pull data from the network.
 use byteorder::{LittleEndian, ReadBytesExt, WriteBytesExt};
 use result::{Error, Result};
 use std::collections::VecDeque;
diff --git a/src/streamer.rs b/src/streamer.rs
index 53055c1ad..368365ec7 100644
--- a/src/streamer.rs
+++ b/src/streamer.rs
@@ -1,3 +1,4 @@
+//! The `streamer` module defines a set of services for effecently pulling data from udp sockets.
 use packet::{Blob, BlobRecycler, PacketRecycler, SharedBlob, SharedPackets, NUM_BLOBS};
 use result::Result;
 use std::collections::VecDeque;
@@ -224,11 +225,15 @@ fn retransmit(
     Ok(())
 }
 
-//service to retransmit messages from the leader to layer 1 nodes
-//see subscriber.rs for network layer definitions
-//window receives blobs from the network
-//for any blobs that originated from the leader, we broadcast
-//to the rest of the network
+/// Service to retransmit messages from the leader to layer 1 nodes.
+/// See `subscribers` for network layer definitions.
+/// # Arguments
+/// * `sock` - Socket to read from.  Read timeout is set to 1.
+/// * `exit` - Boolean to signal system exit.
+/// * `subs` - Shared Subscriber structure.  This structure needs to be updated and popualted by
+/// the accountant.
+/// * `recycler` - Blob recycler.
+/// * `r` - Receive channel for blobs to be retransmitted to all the layer 1 nodes.
 pub fn retransmitter(
     sock: UdpSocket,
     exit: Arc<AtomicBool>,
diff --git a/src/subscribers.rs b/src/subscribers.rs
index 67273e0d0..a0c2cfdd7 100644
--- a/src/subscribers.rs
+++ b/src/subscribers.rs
@@ -1,3 +1,9 @@
+//! The `subscribers` module defines data structures to keep track of nodes on the network.
+//! The network is arranged in layers:
+//! * layer 0, leader
+//! * layer 1, as many nodes as we can fit to quickly get reliable 2/3+1 finality
+//! * layer 2, everyone else, if layer 1 is 2**10, layer 2 should be 2**20 number of nodes
+//! It's up to the external state machine to keep this updated.
 use packet::Blob;
 use rayon::prelude::*;
 use result::{Error, Result};
@@ -30,10 +36,6 @@ impl Node {
     }
 }
 
-//Subscriber data structure
-//layer 0, leader
-//layer 1, as many nodes as we can fit to quickly get reliable 2/3+1 finality
-//layer 2, everyone else, if layer 1 is 2**10, layer 2 should be 2**20 number of nodes
 pub struct Subscribers {
     data: Vec<Node>,
     me: Node,
@@ -51,7 +53,7 @@ impl Subscribers {
         h
     }
 
-    //retransmit messages from the leader to layer 1 nodes
+    /// retransmit messages from the leader to layer 1 nodes
     pub fn retransmit(&self, blob: &mut Blob, s: &UdpSocket) -> Result<()> {
         let errs: Vec<_> = self.data
             .par_iter()