Comments.

2 files changed, 17 insertions, 2 deletions

diff --git a/Presence/Presence.hs b/Presence/Presence.hs
index f1bae255..41204818 100644
--- a/Presence/Presence.hs
+++ b/Presence/Presence.hs
@@ -502,6 +502,9 @@ peerKeyToResolvedName buds pk = do
     return $ fromMaybe (peerKeyToText pk) (listToMaybe ns')
 
 
+-- Given a local address and an IP-address JID, we return True if the JID is
+-- local, False otherwise.  Additionally, a list of equivalent hostname JIDS
+-- are returned.
 multiplyJIDForClient :: SockAddr -> Text -> IO (Bool,[(Maybe Text,Text,Maybe Text)])
 multiplyJIDForClient laddr jid = do
     let (n,h,r) = splitJID jid
@@ -819,6 +822,8 @@ answerProbe state mto k chan = do
         pstanza <- makePresenceStanza "jabber:server" (Just jid) Offline
         atomically $ writeTChan (connChan conn) pstanza
 
+-- Send friend requests and remote presences stored in remotesByPeer to XMPP
+-- clients.
 sendCachedPresence :: PresenceState -> ConnectionKey -> IO ()
 sendCachedPresence state k = do
     forClient state k (return ()) $ \client -> do
@@ -888,7 +893,9 @@ modifyRosterFile :: (Traversable t, MonadPlus t) =>
                    -> t1)
                   -> Text -- user
                   -> Text -- profile
-                  -> Text -> [SockAddr] -> Bool -> t1
+                  -> Text
+                  -> [SockAddr] -- If a JID reverse-resolves to this address, consider it same.
+                  -> Bool -> t1
 modifyRosterFile doit whose profile to addrs bAdd = do
     let (mu,_,_) = splitJID to
         cmp jid = runTraversableT $ do
@@ -1058,6 +1065,7 @@ peerSubscriptionRequest state fail k stanza chan = do
 
     let from' = unsplitJID fromtup
 
+    -- Update roster files (subscribe: add to pending, unsubscribe: remove from subscribers).
     already_pending <-
       if is_wanted then
         addToRosterFile ConfigFiles.modifyPending u profile from' addrs
diff --git a/Presence/XMPPServer.hs b/Presence/XMPPServer.hs
index bcd75ee2..520242cf 100644
--- a/Presence/XMPPServer.hs
+++ b/Presence/XMPPServer.hs
@@ -267,6 +267,7 @@ addrToText (addr@(SockAddrInet6 _ _ _ _)) = Text.pack $ stripColon (show addr)
           where
             (pre,bracket) = break (==']') s
 
+-- Shows (as Text) the IP address associated with the given ConnectionKey.
 peerKeyToText :: ConnectionKey -> Text
 peerKeyToText (PeerKey { callBackAddress=addr }) = addrToText addr
 peerKeyToText (ClientKey { localAddress=addr }) = "ErrorClIeNt0"
@@ -462,6 +463,9 @@ sendModifiedStanzaToPeer stanza chan = do
     processedType x = x
 
 
+-- Modifies a server-to-server stanza to send it to a client.  This changes the
+-- namespace and also filters some non-supported attributes.  Any other
+-- modifications need to be made by the caller.
 sendModifiedStanzaToClient :: Stanza -> TChan Stanza -> IO ()
 sendModifiedStanzaToClient stanza chan = do
     (echan,clsrs,quitvar) <- conduitToChan c
@@ -1181,7 +1185,10 @@ simulateChatError err mfrom =
     ]
 
 
-presenceSolicitation :: Text -> Text -> IO Stanza
+-- | Create a friend-request stanza.
+presenceSolicitation :: Text -- ^ JID of sender making request.
+                     -> Text -- ^ JID of recipient who needs to approve it.
+                     -> IO Stanza
 presenceSolicitation = presenceStanza (PresenceRequestSubscription True) "subscribe"
 
 presenceProbe :: Text -> Text -> IO Stanza