documentation clarification and some formatting

source/Network/Xmpp/Concurrent/Monad.hs

@@ -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)
+    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)

source/Network/Xmpp/Monad.hs

@@ -83,7 +83,8 @@ 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.
+-- Pulls a stanza (or stream error) from the stream. Throws an error on a stream
+-- error.
 pullStanza :: XmppConMonad Stanza
 pullStanza = do
     res <- pullPickle xpStreamStanza