fix some outdated comments

source/Network/Xmpp/Concurrent/Threads.hs

@@ -26,8 +26,6 @@ readWorker :: (Stanza -> IO ())
 readWorker onStanza onCClosed stateRef = forever . Ex.mask_ $ do
 
     s' <- Ex.catches ( do
-                   -- we don't know whether pull will
-                   -- necessarily be interruptible
                         atomically $ do
                             s@(Stream con) <- readTMVar stateRef
                             scs <- streamConnectionState <$> readTMVar con
@@ -44,6 +42,8 @@ readWorker onStanza onCClosed stateRef = forever . Ex.mask_ $ do
         Nothing -> return ()
         Just s -> do
             res <- Ex.catches (do
+                   -- we don't know whether pull will
+                   -- necessarily be interruptible
                              allowInterrupt
                              res <- pullStanza s
                              case res of
@@ -70,9 +70,7 @@ readWorker onStanza onCClosed stateRef = forever . Ex.mask_ $ do
     allowInterrupt = unsafeUnmask $ return ()
     -- While waiting for the first semaphore(s) to flip we might receive another
     -- interrupt. When that happens we add it's semaphore to the list and retry
-    -- waiting. We do this because we might receive another
+    -- waiting.
-    -- interrupt while we're waiting for a mutex to unlock; if that happens, the
-    -- new interrupt is added to the list and is waited for as well.
     handleInterrupts :: [TMVar ()] -> IO [()]
     handleInterrupts ts =
         Ex.catch (atomically $ forM ts takeTMVar)
@@ -81,9 +79,6 @@ readWorker onStanza onCClosed stateRef = forever . Ex.mask_ $ do
     stateIsClosed Finished = True
     stateIsClosed _        = False
 
-
--- Two streams: input and output. Threads read from input stream and write to
--- output stream.
 -- | Runs thread in XmppState monad. Returns channel of incoming and outgoing
 -- stances, respectively, and an Action to stop the Threads and close the
 -- connection.

source/Network/Xmpp/Stream.hs

@@ -464,7 +464,7 @@ pullStanza = withStream' $ do
         Right (Right r) -> return $ Right r
 
 -- Performs the given IO operation, catches any errors and re-throws everything
--- except 'ResourceVanished' and IllegalOperation, in which case it will return False instead
+-- except 'ResourceVanished' and IllegalOperation, which it will return.
 catchPush :: IO () -> IO (Either XmppFailure ())
 catchPush p = ExL.catch
     (p >> return (Right ()))
@@ -547,11 +547,7 @@ createStream realm config = do
             "."
         return d
 
--- Connects to the provided hostname or IP address. If a hostname is provided, a
+-- Connects using the specified method. Returns the Handle acquired, if any.
--- DNS-SRV lookup is performed (unless `sockAddr' has been specified, in which
--- case that address is used instead). If an A(AAA) record results are
--- encountered, all IP addresses will be tried until a successful connection
--- attempt has been made. Will return the Handle acquired, if any.
 connect :: HostName -> StreamConfiguration -> ErrorT XmppFailure IO
            (Maybe StreamHandle)
 connect realm config = do