Documented Network.Lossless.

1 files changed, 18 insertions, 10 deletions

diff --git a/src/Network/Lossless.hs b/src/Network/Lossless.hs
index f48dc8fd..ff0b8cc1 100644
--- a/src/Network/Lossless.hs
+++ b/src/Network/Lossless.hs
@@ -1,3 +1,9 @@
+-- | This module uses 'Data.PacketBuffer' appropriately to implement a reliable
+-- transport over an underlying lossy one.
+--
+-- It was written to be a helper to 'Network.Tox.Session' but it is
+-- representation-agnostic and so could potentially be used on an unrelated
+-- lossy transport.
 {-# LANGUAGE CPP           #-}
 {-# LANGUAGE LambdaCase    #-}
 {-# LANGUAGE TupleSections #-}
@@ -19,21 +25,23 @@ import Control.Concurrent.Lifted.Instrument
 import Control.Concurrent.Lifted
 #endif
 
+-- | Sequencing information for a packet.
 data SequenceInfo = SequenceInfo
-    { sequenceNumber :: {-# UNPACK #-} !Word32
-    , sequenceAck    :: {-# UNPACK #-} !Word32
+    { sequenceNumber :: {-# UNPACK #-} !Word32 -- ^ Packets are ordered by their 'sequenceNumber'.
+    , sequenceAck    :: {-# UNPACK #-} !Word32 -- ^ This is the sender's latest received in-order packet.
     }
  deriving (Eq,Ord,Show)
 
+-- | Obtain a reliable transport form an unreliable one.
 lossless :: Show addr =>
-            (x -> addr -> IO (PacketInboundEvent (x',addr')))
-            -> (SequenceInfo -> x' -> addr' -> IO (Bool,y))
-            -> addr
-            -> TransportA String addr x y
-            -> IO ( Transport String addr' x'
-                  , [Word32] -> IO ()
-                  , IO ([Word32],Word32)
-                  )
+    (x -> addr -> IO (PacketInboundEvent (x',addr'))) -- ^ Used to classify newly arrived packets.
+    -> (SequenceInfo -> x' -> addr' -> IO (Bool,y))   -- ^ Used to encode and classify outbound packets.
+    -> addr                                           -- ^ The remote address for this session.
+    -> TransportA String addr x y                     -- ^ An unreliable lossy transport.
+    -> IO ( Transport String addr' x' -- ^ A reliable lossless transport.
+          , [Word32] -> IO ()         -- ^ Use this to request lost packets be re-sent.
+          , IO ([Word32],Word32)      -- ^ Use this to discover missing packets to request.
+          )
 lossless isLossless encode saddr udp = do
     pb <- atomically newPacketBuffer
     oob <- atomically newTChan -- Out-of-band channel, these packets (or