additional cleanups and documentation fixes

source/Network/Xmpp.hs

@@ -54,12 +54,14 @@ module Network.Xmpp
   , StreamConfiguration(..)
   , SessionConfiguration(..)
   , ConnectionDetails(..)
+  , ConnectionState(..)
   , closeConnection
   , endSession
   , waitForStream
     -- ** Authentication handlers
     -- | The use of 'scramSha1' is /recommended/, but 'digestMd5' might be
     -- useful for interaction with older implementations.
+  , SaslHandler
   , AuthData
   , Username
   , Password
@@ -211,11 +213,19 @@ module Network.Xmpp
   -- | Network.Xmpp doesn't re-export the accessors to avoid name
   -- clashes. To use them import Network.Xmpp.Lens
   , module Network.Xmpp.Lens
-  -- * Miscellaneous
+  -- * Plugins
+  -- Plugins modify incoming and outgoing stanzas. They can, for example, handle
+  -- encryption, compression or other protocol extensions.
+  , Annotated(..)
+  , Annotation(..)
+  , Plugin
+  , Plugin'(..)
+  -- * LangTag
   , LangTag
   , langTagFromText
   , langTagToText
   , parseLangTag
+  -- * Miscellaneous
   , XmppFailure(..)
   , StreamErrorInfo(..)
   , StreamErrorCondition(..)
@@ -223,10 +233,6 @@ module Network.Xmpp
                , AuthSaslFailure
                , AuthIllegalCredentials
                , AuthOtherFailure )
-  , SaslHandler
-  , Plugin
-  , Plugin'
-  , ConnectionState(..)
   , connectTls
   , def
   ) where

source/Network/Xmpp/Concurrent/Types.hs

@@ -38,6 +38,10 @@ type Resource = Text
 -- It is recommended to leave the resource up to the server
 type AuthData = Maybe (ConnectionState -> [SaslHandler] , Maybe Resource)
 
+-- | Annotations are auxiliary data attached to received stanzas by 'Plugin's to
+-- convey information regarding their operation. For example, a plugin for
+-- encryption might attach information about whether a received stanza was
+-- encrypted and which algorithm was used.
 data Annotation = forall f.(Typeable f, Show f) => Annotation{fromAnnotation :: f}
 
 instance Show Annotation where
@@ -49,17 +53,19 @@ type Annotated a = (a, [Annotation])
 getAnnotation :: Typeable b => Annotated a -> Maybe b
 getAnnotation = foldr (\(Annotation a) b -> maybe b Just $ cast a) Nothing . snd
 
-data Plugin' = Plugin' { inHandler :: Stanza
+data Plugin' = Plugin'
+    { -- | Resulting stanzas and additional Annotations
+      inHandler :: Stanza
                 -> [Annotation]
                 -> IO [(Stanza, [Annotation])]
     , outHandler :: Stanza -> IO (Either XmppFailure ())
-                          -- | In order to allow plugins to tie the knot (Plugin
+    -- | In order to allow plugins to tie the knot (Plugin / Session) we pass
-                          -- / Session) we pass the plugin the completed Session
+    -- the plugin the completed Session once it exists
-                          -- once it exists
     , onSessionUp :: Session -> IO ()
     }
 
-type Plugin = (Stanza -> IO (Either XmppFailure ()))
+type Plugin = (Stanza -> IO (Either XmppFailure ())) -- ^ pass stanza to next
+                                                     -- plugin
               -> ErrorT XmppFailure IO Plugin'
 
 -- | Configuration for the @Session@ object.