From f48b30127efbbeeb30a1fdd6e202fc52e1ee6e3a Mon Sep 17 00:00:00 2001
From: Sam Truzjan <pxqr.sta@gmail.com>
Date: Thu, 27 Feb 2014 14:40:30 +0400
Subject: Update tracker RPC documentation

---
 src/Network/BitTorrent/Tracker/RPC.hs      | 18 +++++++++++++++---
 src/Network/BitTorrent/Tracker/RPC/HTTP.hs |  8 ++++----
 src/Network/BitTorrent/Tracker/RPC/UDP.hs  |  9 +++++++--
 3 files changed, 26 insertions(+), 9 deletions(-)

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

diff --git a/src/Network/BitTorrent/Tracker/RPC.hs b/src/Network/BitTorrent/Tracker/RPC.hs
index 3acffce9..b3e962fa 100644
--- a/src/Network/BitTorrent/Tracker/RPC.hs
+++ b/src/Network/BitTorrent/Tracker/RPC.hs
@@ -5,7 +5,11 @@
 --   Stability   :  experimental
 --   Portability :  portable
 --
---   Protocol independent bittorrent tracker API.
+--   This module provides unified RPC interface to BitTorrent
+--   trackers. The tracker is an UDP/HTTP/HTTPS service used to discovery
+--   peers for a particular existing torrent and keep statistics about
+--   the swarm. This module also provides a way to easily request
+--   scrape info for a particular torrent list.
 --
 {-# LANGUAGE DeriveDataTypeable #-}
 module Network.BitTorrent.Tracker.RPC
@@ -104,18 +108,26 @@ data Manager  = Manager
   , udpMgr   :: !UDP.Manager
   }
 
--- | Normally a bittorrent client session need a single RPC manager
--- only.
+-- | Create a new 'Manager'. You /must/ manually 'closeManager'
+-- otherwise resource leakage is possible. Normally, a bittorrent
+-- client need a single RPC manager only.
+--
+--   This function can throw 'IOException' on invalid 'Options'.
+--
 newManager :: Options -> PeerInfo -> IO Manager
 newManager opts info = do
   h <- HTTP.newManager (optHttpRPC opts)
   u <-  UDP.newManager (optUdpRPC  opts) `onException` HTTP.closeManager h
   return $ Manager opts info h u
 
+-- | Close all pending RPCs. Behaviour of currently in-flight RPCs can
+-- differ depending on underlying protocol used. No rpc calls should
+-- be performed after manager becomes closed.
 closeManager :: Manager -> IO ()
 closeManager Manager {..} = do
   UDP.closeManager udpMgr `finally` HTTP.closeManager httpMgr
 
+-- | Normally you need to use 'Control.Monad.Trans.Resource.allocate'.
 withManager :: Options -> PeerInfo -> (Manager -> IO a) -> IO a
 withManager opts info = bracket (newManager opts info) closeManager
 
diff --git a/src/Network/BitTorrent/Tracker/RPC/HTTP.hs b/src/Network/BitTorrent/Tracker/RPC/HTTP.hs
index 00fc9331..37ddb5ad 100644
--- a/src/Network/BitTorrent/Tracker/RPC/HTTP.hs
+++ b/src/Network/BitTorrent/Tracker/RPC/HTTP.hs
@@ -5,10 +5,7 @@
 --   Stability   :  provisional
 --   Portability :  portable
 --
---   The tracker is an HTTP/HTTPS service used to discovery peers for
---   a particular existing torrent and keep statistics about the
---   swarm. This module also provides a way to easily request scrape
---   info for a particular torrent list.
+--   This module implement HTTP tracker protocol.
 --
 --   For more information see:
 --   <https://wiki.theory.org/BitTorrentSpecification#Tracker_HTTP.2FHTTPS_Protocol>
@@ -102,12 +99,15 @@ data Manager = Manager
   , httpMgr :: !HTTP.Manager
   }
 
+-- |
 newManager :: Options -> IO Manager
 newManager opts = Manager opts <$> HTTP.newManager (optHttpOptions opts)
 
+-- |
 closeManager :: Manager -> IO ()
 closeManager Manager {..} = HTTP.closeManager httpMgr
 
+-- | Normally you need to use 'Control.Monad.Trans.Resource.allocate'.
 withManager :: Options -> (Manager -> IO a) -> IO a
 withManager opts = bracket (newManager opts) closeManager
 
diff --git a/src/Network/BitTorrent/Tracker/RPC/UDP.hs b/src/Network/BitTorrent/Tracker/RPC/UDP.hs
index 632e3d86..160397dd 100644
--- a/src/Network/BitTorrent/Tracker/RPC/UDP.hs
+++ b/src/Network/BitTorrent/Tracker/RPC/UDP.hs
@@ -5,7 +5,8 @@
 --   Stability   :  provisional
 --   Portability :  portable
 --
---   This module implement low-level UDP tracker protocol.
+--   This module implement UDP tracker protocol.
+--
 --   For more info see:
 --   <http://www.bittorrent.org/beps/bep_0015.html>
 --
@@ -142,6 +143,7 @@ type PendingResponse     = MVar (Either RpcException Response)
 type PendingTransactions = Map TransactionId PendingResponse
 type PendingQueries      = Map SockAddr      PendingTransactions
 
+-- | UDP tracker manager.
 data Manager = Manager
   { options         :: !Options
   , sock            :: !Socket
@@ -176,7 +178,7 @@ resetState Manager {..} = do
   where
     err = error "UDP tracker manager closed"
 
--- | This function will throw 'IOException' if or
+-- | This function will throw 'IOException' on invalid 'Options'.
 newManager :: Options -> IO Manager
 newManager opts = do
   checkOptions opts
@@ -185,6 +187,8 @@ newManager opts = do
   putMVar (listenerThread mgr) tid
   return mgr
 
+-- | Unblock all RPCs by throwing 'ManagerClosed' exception. No rpc
+-- calls should be performed after manager becomes closed.
 closeManager :: Manager -> IO ()
 closeManager Manager {..} = do
   close sock
@@ -193,6 +197,7 @@ closeManager Manager {..} = do
     Nothing  -> return ()
     Just tid -> killThread tid
 
+-- | Normally you need to use 'Control.Monad.Trans.Resource.allocate'.
 withManager :: Options -> (Manager -> IO a) -> IO a
 withManager opts = bracket (newManager opts) closeManager
 
-- 
cgit v1.2.3