2 files changed, 30 insertions, 53 deletions

diff --git a/src/Network/KRPC.hs b/src/Network/KRPC.hs
index 286c063e..a1767161 100644
--- a/src/Network/KRPC.hs
+++ b/src/Network/KRPC.hs
@@ -6,8 +6,8 @@
 --   Portability :  portable
 --
 --   This module provides safe remote procedure call. One important
---   point is exceptions and errors, so be able handle them properly
---   we need to investigate a bit about how this all works.
+--   point is exceptions and errors, so to be able handle them
+--   properly we need to investigate a bit about how this all works.
 --   Internally, in order to make method invokation KRPC makes the
 --   following steps:
 --
@@ -41,50 +41,14 @@
 --     * Caller extracts results and finally return results of the
 --     procedure call as ordinary haskell values.
 --
---   If every other error occurred caller get the 'GenericError'. All
---   errors returned by callee are throwed as ordinary haskell
---   exceptions at caller side. Make sure that both callee and caller
---   uses the same method signatures and everything should be ok: this
---   KRPC implementation provides some level of safety through
---   types. Also note that both caller and callee use plain UDP, so
---   KRPC is unreliable.
+--   If every other error occurred then caller get the
+--   'GenericError'. All errors returned by callee are throwed as
+--   ordinary haskell exceptions at caller side. Also note that both
+--   caller and callee use plain UDP, so KRPC is unreliable.
 --
---   Consider one tiny example. From now @caller = client@ and
---   @callee = server or remote@.
+--   For async 'query' use @async@ package.
 --
---   Somewhere we have to define all procedure signatures. Imagine
---   that this is a library shared between client and server:
---
---   >  factorialMethod :: Method Int Int
---   >  factorialMethod = method "factorial" ["x"] ["y"]
---
---   Otherwise you can define this code in both client and server of
---   course. But in this case you might get into troubles: you can get
---   'MethodUnknown' or 'ProtocolError' if name or type of method
---   will mismatch after not synced changes in client or server code.
---
---   Now let's define our client-side:
---
---   > main = withRemote  $ \remote -> do
---   >    result <- call remote (0, 6000) factorialMethod 4
---   >    assert (result == 24) $ print "Success!"
---
---   It basically open socket with 'withRemote' and make all the other
---   steps in 'call' as describe above. And finally our server-side:
---
---   > factorialImpl :: Int -> Int
---   > factorialImpl n = product [1..n]
---   >
---   > main = runServer [factorialMethod $ return . factorialImpl]
---
---   Here we implement method signature from that shared lib and run
---   server with runServer by passing method table in.
---
---   For async API use /async/ package, old API have been removed.
---
---   For more examples see @exsamples@ or @tests@ directories.
---
---   For protocol details see 'Remote.KRPC.Protocol' module.
+--   For protocol details see "Network.KRPC.Message" module.
 --
 module Network.KRPC
        ( -- * Methods
diff --git a/src/Network/KRPC/Manager.hs b/src/Network/KRPC/Manager.hs
index a8c90b33..a883a34a 100644
--- a/src/Network/KRPC/Manager.hs
+++ b/src/Network/KRPC/Manager.hs
@@ -50,8 +50,13 @@ type CallRes            = MVar KResult
 type PendingCalls       = IORef (Map CallId CallRes)
 
 type HandlerBody h = SockAddr -> BValue -> h (BE.Result BValue)
+
+-- | Handler is a function which will be invoked then some /remote/
+-- node querying /this/ node.
 type Handler     h = (MethodName, HandlerBody h)
 
+-- | Keep track pending queries made by /this/ node and handle queries
+-- made by /remote/ nodes.
 data Manager h = Manager
   { sock               :: !Socket
   , queryTimeout       :: !Int -- ^ in seconds
@@ -61,12 +66,15 @@ data Manager h = Manager
   , handlers           :: [Handler h]
   }
 
+-- | A monad which can perform or handle queries.
 class (MonadBaseControl IO m, MonadIO m) => MonadKRPC h m | m -> h where
+  -- | Ask for manager.
   getManager :: m (Manager h)
 
   default getManager :: MonadReader (Manager h) m => m (Manager h)
   getManager = ask
 
+  -- | Can be used to add logging for instance.
   liftHandler :: h a -> m a
 
   default liftHandler :: m a -> m a
@@ -87,7 +95,11 @@ seedTransaction = 0
 defaultQueryTimeout :: Int
 defaultQueryTimeout = 120
 
-newManager :: SockAddr -> [Handler h] -> IO (Manager h)
+-- | Bind socket to the specified address. To enable query handling
+-- run 'listen'.
+newManager :: SockAddr       -- ^ address to listen on;
+           -> [Handler h]    -- ^ handlers to run on incoming queries.
+           -> IO (Manager h) -- ^ new manager.
 newManager servAddr handlers = do
     sock  <- bindServ
     tref  <- newEmptyMVar
@@ -110,18 +122,19 @@ closeManager Manager {..} = do
   -- TODO unblock calls
   close sock
 
--- | Normally you should use Control.Monad.Trans.allocate function.
+-- | Normally you should use Control.Monad.Trans.Resource.allocate
+-- function.
 withManager :: SockAddr -> [Handler h] -> (Manager h -> IO a) -> IO a
 withManager addr hs = bracket (newManager addr hs) closeManager
 
-sendMessage :: MonadIO m => BEncode a => Socket -> SockAddr -> a -> m ()
-sendMessage sock addr a = do
-  liftIO $ sendManyTo sock (BL.toChunks (BE.encode a)) addr
-
 {-----------------------------------------------------------------------
 --  Client
 -----------------------------------------------------------------------}
 
+sendMessage :: MonadIO m => BEncode a => Socket -> SockAddr -> a -> m ()
+sendMessage sock addr a = do
+  liftIO $ sendManyTo sock (BL.toChunks (BE.encode a)) addr
+
 genTransactionId :: TransactionCounter -> IO TransactionId
 genTransactionId ref = do
   cur <- atomicModifyIORef' ref $ \ cur -> (succ cur, cur)
@@ -148,7 +161,7 @@ queryResponse ares = do
     Right r -> pure r
     Left  e -> throwIO $ decodeError e respId
 
--- |
+-- | Enqueue query to the given node.
 --
 --  This function will throw exception if quered node respond with
 --  @error@ message or timeout expires.
@@ -178,8 +191,8 @@ query addr params = do
 --  Handlers
 -----------------------------------------------------------------------}
 
--- | Any thrown exception will be supressed and send over wire back to
--- the quering node.
+-- | Make handler from handler function. Any thrown exception will be
+-- supressed and send over the wire back to the querying node.
 handler :: forall h a b. (KRPC a b, Monad h)
         => (SockAddr -> a -> h b) -> Handler h
 handler body = (name, wrapper)