Remove unnecessary attributes and add doc comments for Mixnet (#618)

mixnet/src/lib.rs

@@ -1,6 +1,6 @@
 //! Mixnet
-// #![deny(missing_docs, warnings)]
-// #![forbid(unsafe_code)]
+#![deny(missing_docs, warnings)]
+#![forbid(unsafe_code)]
 
 /// Mix node address
 pub mod address;
@@ -13,7 +13,9 @@ pub mod error;
 mod fragment;
 /// Mix node
 pub mod node;
+/// Mix packet
 pub mod packet;
+/// Poisson distribution
 mod poisson;
 /// Mixnet topology
 pub mod topology;

mixnet/src/packet.rs

@@ -10,6 +10,7 @@ use crate::{
     topology::MixnetTopology,
 };
 
+/// A packet to be sent through the mixnet
 #[derive(Clone, PartialEq, Eq, Debug)]
 pub struct Packet {
     address: NodeAddress,
@@ -74,18 +75,23 @@ impl Packet {
         Ok(packets)
     }
 
+    /// Returns the address of the mix node that this packet is being sent to
     pub fn address(&self) -> NodeAddress {
         self.address
     }
 
+    /// Returns the body of the packet
     pub fn body(self) -> PacketBody {
         self.body
     }
 }
 
+/// The body of a packet to be sent through the mixnet
 #[derive(Clone, PartialEq, Eq, Debug)]
 pub enum PacketBody {
+    /// A Sphinx packet to be sent to the next mix node
     SphinxPacket(Vec<u8>),
+    /// A fragment that has been through the mixnet and can be reconstructed into the original message
     Fragment(Vec<u8>),
 }
 
@@ -110,6 +116,7 @@ impl TryFrom<sphinx_packet::payload::Payload> for PacketBody {
 }
 
 impl PacketBody {
+    /// Consumes the packet body and serialize it into a byte array
     pub fn bytes(self) -> Box<[u8]> {
         match self {
             Self::SphinxPacket(data) => Self::bytes_with_flag(PacketBodyFlag::SphinxPacket, data),
@@ -125,6 +132,7 @@ impl PacketBody {
         out.into_boxed_slice()
     }
 
+    /// Deserialize a packet body from a reader
     pub async fn read_from<R: AsyncRead + Unpin>(
         reader: &mut R,
     ) -> io::Result<Result<Self, MixnetError>> {

mixnet/src/poisson.rs

@@ -5,11 +5,11 @@ use rand_distr::{Distribution, Exp};
 
 use crate::error::MixnetError;
 
-#[allow(dead_code)]
+/// A Poisson process that models the times at which events occur.
 pub struct Poisson(Exp<f64>);
 
 impl Poisson {
-    #[allow(dead_code)]
+    /// Create a new Poisson process with the given rate per minute.
     pub fn new(rate_per_min: f64) -> Result<Self, MixnetError> {
         Ok(Self(Exp::new(rate_per_min)?))
     }
@@ -18,7 +18,6 @@ impl Poisson {
     ///
     /// If events occur in a Poisson distribution with rate_per_min,
     /// the interval between events follow the exponential distribution with rate_per_min.
-    #[allow(dead_code)]
     pub fn interval<R: Rng + ?Sized>(&self, rng: &mut R) -> Duration {
         // generate a random value from the distribution
         let interval_min = self.0.sample(rng);