From 47d8fcac4924f95d352994d064ff02d58d938d42 Mon Sep 17 00:00:00 2001
From: Jon Kristensen <info@jonkri.com>
Date: Mon, 26 Aug 2013 14:15:33 +0200
Subject: [PATCH] Apply some additional minor Haddock fixes

---
 source/Network/Xmpp/Concurrent.hs         | 30 ++++++++++++++---------
 source/Network/Xmpp/Concurrent/Message.hs |  3 ++-
 source/Network/Xmpp/Concurrent/Monad.hs   | 13 ++++++----
 3 files changed, 29 insertions(+), 17 deletions(-)

diff --git a/source/Network/Xmpp/Concurrent.hs b/source/Network/Xmpp/Concurrent.hs
index fa1d239..aa82678 100644
--- a/source/Network/Xmpp/Concurrent.hs
+++ b/source/Network/Xmpp/Concurrent.hs
@@ -195,8 +195,11 @@ session realm mbSasl config = runErrorT $ do
     liftIO $ when (enableRoster config) $ initRoster ses
     return ses
 
--- | Reconnect immediately with the stored settings. Returns Just the error when
--- the reconnect attempt fails and Nothing when no failure was encountered
+-- | Reconnect immediately with the stored settings. Returns @Just@ the error
+-- when the reconnect attempt fails and Nothing when no failure was encountered.
+--
+-- This function does not set your presence to online, so you will have to do
+-- this yourself.
 reconnectNow :: Session -- ^ session to reconnect
           -> IO (Maybe XmppFailure)
 reconnectNow sess@Session{conf = config, reconnectWait = rw} = do
@@ -234,17 +237,20 @@ reconnectNow sess@Session{conf = config, reconnectWait = rw} = do
             return Nothing
 
 
--- | Reconnect with the stored settings. Returns a list of errors when the
--- reconnect attempt fail and Nothing when no failure was encountered
+-- | Reconnect with the stored settings.
 --
 -- Waits a random amount of seconds (between 0 and 60 inclusive) before the
 -- first attempt and an increasing amount after each attempt after that. Caps
 -- out at 2-5 minutes.
-reconnect :: Integer -- ^ maximum number of retries (Nothing for
-                     -- unbounded). Numbers of 1 or less will perform exactly
-                     -- one retry
-          -> Session -- ^ session to reconnect
-          -> IO (Bool, [XmppFailure]) -- ^ The failure modes of the retries
+--
+-- This function does not set your presence to online, so you will have to do
+-- this yourself.
+reconnect :: Integer -- ^ Maximum number of retries (numbers of 1 or less will
+                     -- perform exactly one retry)
+          -> Session -- ^ Session to reconnect
+          -> IO (Bool, [XmppFailure]) -- ^ Whether or not the reconnect attempt
+                                      -- was successful, and a list of failure
+                                      -- modes encountered
 reconnect maxTries sess = go maxTries
   where
     go t = do
@@ -260,8 +266,10 @@ reconnect maxTries sess = go maxTries
 -- first attempt and an increasing amount after each attempt after that. Caps
 -- out at 2-5 minutes.
 --
-reconnect' :: Session -- ^ session to reconnect
-          -> IO Integer -- ^ number of failed retries before connection could be
+-- This function does not set your presence to online, so you will have to do
+-- this yourself.
+reconnect' :: Session -- ^ Session to reconnect
+          -> IO Integer -- ^ Number of failed retries before connection could be
                         -- established
 reconnect' sess = go 0
   where
diff --git a/source/Network/Xmpp/Concurrent/Message.hs b/source/Network/Xmpp/Concurrent/Message.hs
index 8413593..c3c7bef 100644
--- a/source/Network/Xmpp/Concurrent/Message.hs
+++ b/source/Network/Xmpp/Concurrent/Message.hs
@@ -52,6 +52,7 @@ filterMessages f g session = do
         Right m | g m -> return $ Right m
                 | otherwise -> filterMessages f g session
 
--- | Send a message stanza. Returns False when the Message could not be sentx
+-- | Send a message stanza. Returns @False@ when the 'Message' could not be
+-- sent.
 sendMessage :: Message -> Session -> IO Bool
 sendMessage m session = sendStanza (MessageS m) session
diff --git a/source/Network/Xmpp/Concurrent/Monad.hs b/source/Network/Xmpp/Concurrent/Monad.hs
index 98782f2..6a894bc 100644
--- a/source/Network/Xmpp/Concurrent/Monad.hs
+++ b/source/Network/Xmpp/Concurrent/Monad.hs
@@ -90,11 +90,14 @@ runHandler :: (EventHandlers -> IO a) -> Session -> IO a
 runHandler h session = h =<< atomically (readTMVar $ eventHandlers session)
 
 
--- | End the current Xmpp session.
--- Kills the associated threads and closes the connection.
+-- | End the current XMPP session. Kills the associated threads and closes the
+-- connection.
+--
+-- Note that XMPP clients (that has signalled availability) should send
+-- \"Unavailable\" presence prior to disconnecting.
 --
 -- The connectionClosedHandler will not be called (to avoid possibly
--- reestablishing the connection)
+-- reestablishing the connection).
 endSession :: Session -> IO ()
 endSession session =  do -- TODO: This has to be idempotent (is it?)
     stopThreads session
@@ -105,8 +108,8 @@ endSession session =  do -- TODO: This has to be idempotent (is it?)
 
 
 -- | 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.
+-- write lock and sending a \</stream:stream\> element), waits (blocks) for
+-- three seconds, and then closes the connection.
 closeConnection :: Session -> IO ()
 closeConnection session = do
     _ <-flip withConnection session $ \stream -> do