From c9ab6d31afc30d42d5d1bee5bffaf76f8608d08a Mon Sep 17 00:00:00 2001
From: joe <joe@jerkface.net>
Date: Thu, 9 Nov 2017 18:33:22 -0500
Subject: More comments.

---
 Presence/XMPPServer.hs | 32 ++++++++++++++++++++------------
 1 file changed, 20 insertions(+), 12 deletions(-)

(limited to 'Presence')

diff --git a/Presence/XMPPServer.hs b/Presence/XMPPServer.hs
index 79167267..2e3c0a37 100644
--- a/Presence/XMPPServer.hs
+++ b/Presence/XMPPServer.hs
@@ -170,8 +170,11 @@ type Stanza = StanzaWrap (LockedChan XML.Event)
 
 data XMPPServerParameters =
     XMPPServerParameters
-    { xmppChooseResourceName :: ConnectionKey -> SockAddr -> Maybe Text -> IO Text
-    , xmppTellMyNameToClient :: IO Text
+    { -- | Called when a client requests a resource id.  The Maybe value is the
+      -- client's preference.
+      xmppChooseResourceName :: ConnectionKey -> SockAddr -> Maybe Text -> IO Text
+    , -- | This should indicate the server's hostname that all client's see.
+      xmppTellMyNameToClient :: IO Text
     , xmppTellMyNameToPeer :: SockAddr -> IO Text
     , xmppTellClientHisName :: ConnectionKey -> IO Text
     , xmppTellPeerHisName :: ConnectionKey -> IO Text
@@ -181,7 +184,9 @@ data XMPPServerParameters =
     , xmppRosterSubscribers  :: ConnectionKey -> IO [Text]
     , xmppRosterSolicited    :: ConnectionKey -> IO [Text]
     , xmppRosterOthers       :: ConnectionKey -> IO [Text]
-    , xmppSubscribeToRoster :: ConnectionKey -> IO ()
+    , -- | Called when after sending a roster to a client.  Usually this  means
+      -- the client status should change from "available" to "interested".
+      xmppSubscribeToRoster :: ConnectionKey -> IO ()
     -- , xmppLookupClientJID :: ConnectionKey -> IO Text
     , xmppTellClientNameOfPeer :: ConnectionKey -> [Text] -> IO Text
     , xmppDeliverMessage :: (IO ()) -> Stanza -> IO ()
@@ -189,11 +194,14 @@ data XMPPServerParameters =
     , xmppInformClientPresence :: ConnectionKey -> Stanza -> IO ()
       -- | Called whenever a remote peer's presence changes.
     , xmppInformPeerPresence :: ConnectionKey -> Stanza -> IO ()
-    , xmppAnswerProbe :: ConnectionKey -> Stanza -> TChan Stanza -> IO ()
+    , -- | Called when a remote peer requests our status.
+      xmppAnswerProbe :: ConnectionKey -> Stanza -> TChan Stanza -> IO ()
     , xmppClientSubscriptionRequest :: IO () -> ConnectionKey -> Stanza -> TChan Stanza -> IO () 
-    , xmppPeerSubscriptionRequest :: IO () -> ConnectionKey -> Stanza -> TChan Stanza -> IO () 
+    , -- | Called when a remote peer sends subscription request.
+      xmppPeerSubscriptionRequest :: IO () -> ConnectionKey -> Stanza -> TChan Stanza -> IO () 
     , xmppClientInformSubscription :: IO () -> ConnectionKey -> Stanza -> IO ()
-    , xmppPeerInformSubscription :: IO () -> ConnectionKey -> Stanza -> IO ()
+    , -- | Called when a remote peer informs us of our subscription status.
+      xmppPeerInformSubscription :: IO () -> ConnectionKey -> Stanza -> IO ()
     , xmppVerbosity :: IO Int
     }
 
@@ -647,15 +655,15 @@ grokPresence ns stanzaTag = do
     let typ = lookupAttrib "type" (tagAttrs stanzaTag)
     case typ of
         Nothing -> parsePresenceStatus ns stanzaTag
-        Just "unavailable" -> fmap (fmap (\p -> p {presenceShow=Offline}))
+        Just "unavailable"  -> fmap (fmap (\p -> p {presenceShow=Offline}))
                                    $ parsePresenceStatus ns stanzaTag
-        Just "error" -> return . Just $ PresenceInformError
+        Just "error"        -> return . Just $ PresenceInformError
         Just "unsubscribed" -> return . Just $ PresenceInformSubscription False
         Just "subscribed"   -> return . Just $ PresenceInformSubscription True
-        Just "probe" -> return . Just $ PresenceRequestStatus
-        Just "unsubscribe" -> return . Just $ PresenceRequestSubscription False
-        Just "subscribe"   -> return . Just $ PresenceRequestSubscription True
-        _ -> return Nothing
+        Just "probe"        -> return . Just $ PresenceRequestStatus
+        Just "unsubscribe"  -> return . Just $ PresenceRequestSubscription False
+        Just "subscribe"    -> return . Just $ PresenceRequestSubscription True
+        _                   -> return Nothing
 
 parseMessage
   :: ( MonadThrow m
-- 
cgit v1.2.3