From 00ab24c3cbcf944ec30d0050b29f6d6526f13eb7 Mon Sep 17 00:00:00 2001
From: Jon Kristensen <jon.kristensen@nejla.com>
Date: Thu, 14 Jun 2012 23:41:30 +0200
Subject: [PATCH] documentation clarification and some formatting

---
 source/Network/Xmpp/Concurrent/Monad.hs | 30 +++++++++++++++----------
 source/Network/Xmpp/Monad.hs            |  5 +++--
 2 files changed, 21 insertions(+), 14 deletions(-)

diff --git a/source/Network/Xmpp/Concurrent/Monad.hs b/source/Network/Xmpp/Concurrent/Monad.hs
index 2cd7652..d29f5ab 100644
--- a/source/Network/Xmpp/Concurrent/Monad.hs
+++ b/source/Network/Xmpp/Concurrent/Monad.hs
@@ -235,8 +235,8 @@ setConnectionClosedHandler eh = do
 -- | Run an event handler.
 runHandler :: (EventHandlers -> IO a) -> Xmpp a
 runHandler h = do
-  eh <- liftIO . atomically . readTVar  =<< asks eventHandlers
-  liftIO $ h eh
+    eh <- liftIO . atomically . readTVar  =<< asks eventHandlers
+    liftIO $ h eh
 
 -- | End the current Xmpp session.
 endSession :: Xmpp ()
@@ -244,15 +244,21 @@ endSession = do -- TODO: This has to be idempotent (is it?)
     void $ withConnection xmppKillConnection
     liftIO =<< asks stopThreads
 
--- | Close the connection to the server.
+-- | Close the connection to the server. Closes the stream (by enforcing a
+-- write lock and sending a </stream:stream> element), waits (blocks) for three
+-- seconds, and then closes the connection.
 closeConnection :: Xmpp ()
 closeConnection = Ex.mask_ $ do
-  write <- asks writeRef
-  send <- liftIO . atomically $ takeTMVar write
-  cc <- sCloseConnection <$> (liftIO . atomically . readTMVar =<< asks conStateRef)
-  liftIO . send $ "</stream:stream>"
-  void . liftIO . forkIO $ do
-    threadDelay 3000000
-    (Ex.try cc) :: IO (Either Ex.SomeException ())
-    return ()
-  liftIO . atomically $ putTMVar write (\_ -> return False)
+    write <- asks writeRef
+    send <- liftIO . atomically $ takeTMVar write
+    cc <- sCloseConnection <$>
+        (liftIO . atomically . readTMVar =<< asks conStateRef)
+    liftIO . send $ "</stream:stream>"
+    void . liftIO . forkIO $ do
+      threadDelay 3000000
+      -- When we close the connection, we close the handle that was used in the
+      -- sCloseConnection above. So even if a new connection has been
+      -- established at this point, it will not be affected by this action.
+      (Ex.try cc) :: IO (Either Ex.SomeException ())
+      return ()
+    liftIO . atomically $ putTMVar write (\_ -> return False)
\ No newline at end of file
diff --git a/source/Network/Xmpp/Monad.hs b/source/Network/Xmpp/Monad.hs
index 0f7d078..f017895 100644
--- a/source/Network/Xmpp/Monad.hs
+++ b/source/Network/Xmpp/Monad.hs
@@ -83,8 +83,9 @@ pullPickle p = do
         Left e -> liftIO . Ex.throwIO $ StreamXMLError e
         Right r -> return r
 
--- Pulls a stanza from the stream. Throws an error on failure.
-pullStanza  :: XmppConMonad Stanza
+-- Pulls a stanza (or stream error) from the stream. Throws an error on a stream
+-- error.
+pullStanza :: XmppConMonad Stanza
 pullStanza = do
     res <- pullPickle xpStreamStanza
     case res of