From 4a89ffe25acd8dd162f1eeddb0cbb2d5c626f3c3 Mon Sep 17 00:00:00 2001
From: Trolli Schmittlauch <t.schmittlauch@orlives.de>
Date: Thu, 27 Feb 2020 22:45:24 +0100
Subject: [PATCH] improve documentation, contributes to #8

---
 src/Hash2Pub/FediChord.hs | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/src/Hash2Pub/FediChord.hs b/src/Hash2Pub/FediChord.hs
index ccd1d16..ea9e1da 100644
--- a/src/Hash2Pub/FediChord.hs
+++ b/src/Hash2Pub/FediChord.hs
@@ -17,15 +17,20 @@ import Network.Socket
 import Data.Time.Clock.System
 
 -- define protocol constants
+-- | static definition of ID length in bits
 idBits :: Integer
 idBits = 256
 
+-- |NodeIDs are Integers wrapped in a newtype, to be able to redefine
+-- their instance behaviour
 newtype NodeID = NodeID { getNodeID :: Integer } deriving (Eq, Show, Enum)
 
+-- |NodeIDs are bounded by the value range of an unsigned Integer of length 'idBits'
 instance Bounded NodeID where
     minBound = NodeID 0
     maxBound = NodeID (2^idBits - 1)
 
+-- |calculations with NodeIDs are modular arithmetic operations
 instance Num NodeID where
     a + b = NodeID $ (getNodeID a + getNodeID b) `mod` (getNodeID maxBound + 1)
     a * b = NodeID $ (getNodeID a * getNodeID b) `mod` (getNodeID maxBound + 1)
@@ -35,7 +40,7 @@ instance Num NodeID where
     signum = NodeID . signum . getNodeID
     abs = NodeID . abs . getNodeID  -- ToDo: make sure that at creation time only IDs within the range are used
 
--- NodeIDs on a ring are assigned an Ordering for finding a preceding node
+-- |NodeIDs on a ring are assigned an Ordering for finding a preceding node.
 -- main idea: a node is preceding (LT) if the way forwards to the other node is smaller than the way backwards
 -- problem: equality of ways /= (a == b), so even equal-way paths don't return EQ. The equality-of-ways case is assigned to LT,
 -- as preceding EpiChord nodes are nodes <=.
@@ -61,7 +66,7 @@ data NodeState = NodeState {
   -- might have to be queried first
   , nodeCache :: Map.Map NodeID CacheEntry
   -- ^ EpiChord node cache with expiry times for nodes
-  -- as the map is ordered, lookups for the closes preceding node can be done using `lookupLE`
+  -- as the map is ordered, lookups for the closes preceding node can be done using @lookupLT@
   , successors :: [NodeID]
   , predecessors :: [NodeID]
   ----- protocol parameters -----
@@ -75,9 +80,12 @@ data NodeState = NodeState {
   , pNumParallelQueries :: Int
   -- ^ number of parallel sent queries
   -- needs to be parameterisable for simulation purposes
-                           }
+  }
 
-type CacheEntry = ( NodeState, SystemTime)
+-- |an entry of the 'nodeCache'
+type CacheEntry = (NodeState  -- ^a node's data
+  , SystemTime -- ^timestamp for cache entry expiration
+                  )
 
 -- Todo: DHT backend can learn potential initial bootstrapping points through the instances mentioned in the received AP-relay messages
 -- needs to know its own domain anyways for ID generation