From fc4d96d32ad986ec36e511588cb6078d4ad2323a Mon Sep 17 00:00:00 2001
From: Sam Truzjan <pxqr.sta@gmail.com>
Date: Thu, 21 Nov 2013 01:09:32 +0400
Subject: Add documentation to PeerAddr module

---
 src/Network/BitTorrent/Core/PeerAddr.hs | 21 +++++++++++++--------
 src/Network/BitTorrent/Core/PeerId.hs   |  1 +
 2 files changed, 14 insertions(+), 8 deletions(-)

(limited to 'src/Network/BitTorrent/Core')

diff --git a/src/Network/BitTorrent/Core/PeerAddr.hs b/src/Network/BitTorrent/Core/PeerAddr.hs
index 0eeaae9d..73aa69fd 100644
--- a/src/Network/BitTorrent/Core/PeerAddr.hs
+++ b/src/Network/BitTorrent/Core/PeerAddr.hs
@@ -5,8 +5,8 @@
 --   Stability   :  experimental
 --   Portability :  portable
 --
---   'PeerAddr' is used to represent peer location. Currently it's
---   just peer IP and peer port but this might be changed later.
+--   'PeerAddr' is used to represent peer address. Currently it's
+--   just peer IP and peer port but this might change in future.
 --
 {-# LANGUAGE TemplateHaskell            #-}
 {-# LANGUAGE StandaloneDeriving         #-}
@@ -53,22 +53,24 @@ instance Serialize PortNumber where
   {-# INLINE put #-}
 
 -- TODO check semantic of ord and eq instances
+-- TODO use SockAddr instead of peerIP and peerPort
 
 -- | Peer address info normally extracted from peer list or peer
 -- compact list encoding.
 data PeerAddr = PeerAddr {
-      peerID   :: Maybe PeerId
+      peerID   :: !(Maybe PeerId)
     , peerIP   :: {-# UNPACK #-} !HostAddress
     , peerPort :: {-# UNPACK #-} !PortNumber
     } deriving (Show, Eq, Ord, Typeable)
 
 $(deriveJSON (L.map toLower . L.dropWhile isLower) ''PeerAddr)
 
+-- | The tracker "announce query" compatible encoding.
 instance BEncode PeerAddr where
   toBEncode (PeerAddr pid pip pport) = toDict $
        "peer id" .=? pid
-    .: "ip"      .=!  pip
-    .: "port"    .=!  pport
+    .: "ip"      .=! pip
+    .: "port"    .=! pport
     .: endDict
 
   fromBEncode = fromDict $ do
@@ -76,12 +78,15 @@ instance BEncode PeerAddr where
              <*>! "ip"
              <*>! "port"
 
+-- | The tracker "compact peer list" compatible encoding. The
+-- 'peerId' is always 'Nothing'.
 instance Serialize PeerAddr where
   put PeerAddr {..} = put peerID >> put peerPort
   {-# INLINE put #-}
   get = PeerAddr Nothing <$> get <*> get
   {-# INLINE get #-}
 
+-- | For more info see: <http://www.bittorrent.org/beps/bep_0023.html>
 getCompactPeerList :: S.Get [PeerAddr]
 getCompactPeerList = many get
 
@@ -112,8 +117,8 @@ connectToPeer p = do
 
 -- | Pretty print peer address in human readable form.
 ppPeer :: PeerAddr -> Doc
-ppPeer p @ PeerAddr {..} = case peerID of
-    Just pid -> ppClientInfo (clientInfo pid) <+> "at" <+> paddr
-    Nothing  -> paddr
+ppPeer p @ PeerAddr {..}
+  | Just pid <- peerID = ppClientInfo (clientInfo pid) <+> "at" <+> paddr
+  |     otherwise      = paddr
   where
     paddr = text (show (peerSockAddr p))
diff --git a/src/Network/BitTorrent/Core/PeerId.hs b/src/Network/BitTorrent/Core/PeerId.hs
index a32aa990..1ae55913 100644
--- a/src/Network/BitTorrent/Core/PeerId.hs
+++ b/src/Network/BitTorrent/Core/PeerId.hs
@@ -61,6 +61,7 @@ import Paths_bittorrent (version)
 
 import Data.Torrent.Client
 
+-- TODO use unpacked form (length is known statically)
 
 -- | Peer identifier is exactly 20 bytes long bytestring.
 newtype PeerId = PeerId { getPeerId :: ByteString }
-- 
cgit v1.2.3