Document AnnouncedKeys type

1 files changed, 23 insertions, 2 deletions

diff --git a/src/Network/Tox/Onion/Handlers.hs b/src/Network/Tox/Onion/Handlers.hs
index af515315..8c3a9a86 100644
--- a/src/Network/Tox/Onion/Handlers.hs
+++ b/src/Network/Tox/Onion/Handlers.hs
@@ -142,9 +142,30 @@ data AnnouncedRoute = AnnouncedRoute NodeInfo (ReturnPath N3)
 toOnionDestination :: AnnouncedRoute -> OnionDestination r
 toOnionDestination (AnnouncedRoute ni rpath) = OnionToOwner ni rpath
 
+-- |
+-- The type 'NodeId' was originally made for the DHT key, but here
+-- we reuse it for user keys (public key/real key).
+--
+-- To find someone using their user (public) key, you search for it on
+-- kademlia. At each iteration of the search, you get a response with
+-- closest known nodes(DHT keys) to the key you are searching for.
+--
+-- To do an 'Announce' so your friends can find you, you do a search to
+-- find the closest nodes to your own user(public) key. At those nodes,
+-- you store a route back to yourself (using Announce message) so your
+-- friends can contact you. This means each node needs to store the
+-- saved routes, and that is the purpose of the 'AnnouncedKeys' data
+-- structure.
+--
 data AnnouncedKeys = AnnouncedKeys
-    { keyByAge :: !(PSQ NodeId (Down POSIXTime)) -- TODO: timeout of 300 seconds
-    , keyAssoc :: !(MinMaxPSQ' NodeId NodeDistance (Int,AnnouncedRoute))
+    { keyByAge :: !(PSQ NodeId (Down POSIXTime{-Time at which they announced to you-})) -- TODO: timeout of 300 seconds
+    , keyAssoc :: !(MinMaxPSQ' NodeId NodeDistance (Int{-count of route usage-},AnnouncedRoute))
+        -- ^ PSQ using NodeId(user/public key) as Key
+        --   and using 'NodeDistance' as priority.
+        --   (smaller number is higher priority)
+        --
+        --  Keeping in a MinMaxPSQ will help us later when we want to make the structure
+        --  bounded. (We simply throw away the most NodeDistant keys.
     }