From 79c368c6eb6004f2a9bd64f564a4beef112678ee Mon Sep 17 00:00:00 2001
From: Philipp Balzarek <p.balzarek@googlemail.com>
Date: Tue, 25 Feb 2014 18:56:24 +0100
Subject: [PATCH] additional cleanups and documentation fixes

---
 source/Network/Xmpp.hs                  | 16 +++++++++-----
 source/Network/Xmpp/Concurrent/Types.hs | 28 +++++++++++++++----------
 2 files changed, 28 insertions(+), 16 deletions(-)

diff --git a/source/Network/Xmpp.hs b/source/Network/Xmpp.hs
index 6334ccb..57476f1 100644
--- a/source/Network/Xmpp.hs
+++ b/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
diff --git a/source/Network/Xmpp/Concurrent/Types.hs b/source/Network/Xmpp/Concurrent/Types.hs
index 360b9d9..1cc670a 100644
--- a/source/Network/Xmpp/Concurrent/Types.hs
+++ b/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
-                                      -> [Annotation]
-                                      -> IO [(Stanza, [Annotation])]
-                       , outHandler :: Stanza -> IO (Either XmppFailure ())
-                          -- | In order to allow plugins to tie the knot (Plugin
-                          -- / Session) we pass the plugin the completed Session
-                          -- once it exists
-                       , onSessionUp :: Session -> IO ()
-                       }
-
-type Plugin = (Stanza -> IO (Either XmppFailure ()))
+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 / Session) we pass
+    -- the plugin the completed Session once it exists
+    , onSessionUp :: Session -> IO ()
+    }
+
+type Plugin = (Stanza -> IO (Either XmppFailure ())) -- ^ pass stanza to next
+                                                     -- plugin
               -> ErrorT XmppFailure IO Plugin'
 
 -- | Configuration for the @Session@ object.