minor formatting and documentation additions

src/Network/XMPP.hs

@@ -1,36 +1,25 @@
--- Copyright © 2010-2012 Jon Kristensen.
--- Copyright 2012 Philipp Balzarek
--- See the LICENSE file in the
--- Pontarius distribution for more details.
-
 -- |
 -- Module:      $Header$
--- Description: Pontarius API
+-- Description: A work in progress client implementation of RFC 6120 (XMPP:
--- Copyright:   Copyright © 2010-2012 Jon Kristensen
+--              Core).
 -- License:     Apache License 2.0
 --
 -- Maintainer:  jon.kristensen@nejla.com
 -- Stability:   unstable
 -- Portability: portable
 --
--- The Extensible Messaging and Presence Protocol (XMPP) is an open technology for
+-- The Extensible Messaging and Presence Protocol (XMPP) is an open technology
--- real-time communication, which powers a wide range of applications including
+-- for real-time communication, which powers a wide range of applications
--- instant messaging, presence, multi-party chat, voice and video calls,
+-- including instant messaging, presence, multi-party chat, voice and video
--- collaboration, lightweight middleware, content syndication, and generalized
+-- calls, collaboration, lightweight middleware, content syndication, and
--- routing of XML data.
+-- generalized routing of XML data. Pontarius an XMPP client library,
--- Pontarius an XMPP client library, implementing the core capabilities of XMPP
+-- implementing the core capabilities of XMPP (RFC 6120).
--- (RFC 6120).
---
--- Developers using this library are assumed to understand how XMPP
--- works.
---
--- This module will be documented soon.
 --
--- Note that we are not recommending anyone to use Pontarius XMPP at
+-- Note that we are not recommending anyone to use Pontarius XMPP at this time
--- this time as it's still in an experimental stage and will have its
+-- as it's still in an experimental stage and will have its API and data types
--- API and data types modified frequently.
+-- modified frequently.
 
-{-# LANGUAGE NoMonomorphismRestriction, OverloadedStrings  #-}
+{-# LANGUAGE NoMonomorphismRestriction, OverloadedStrings #-}
 
 module Network.XMPP
   ( -- * Session management
@@ -46,37 +35,37 @@ module Network.XMPP
   , setConnectionClosedHandler
   -- * JID
   -- | A JID (historically: Jabber ID) is XMPPs native format
-  -- for addressing entities in the network. It is somewhat similar to an
+  -- for addressing entities in the network. It is somewhat similar to an e-mail
-  -- email-address but contains three parts instead of two:
+  -- address but contains three parts instead of two:
   , JID(..)
   -- * Stanzas
-  -- | @Stanzas@ are the the smallest unit of communication in @XMPP@. They
+  -- | @Stanzas@ are the the smallest unit of communication in @XMPP@. They come
-  -- come in 3 flavors:
+  -- in 3 flavors:
   --
-  --  * @'Message'@, for traditional IM-style message passing between peers
+  --  * @'Message'@, for traditional push-style message passing between peers
   --
   --  * @'Presence'@, for communicating status updates
   --
-  --  * IQ (info/query), with a request-response semantics
+  --  * IQ (info/query), for request-response semantics communication
   --
   -- All stanza types have the following attributes in common:
   --
-  --  * The /id/ attribute is used by the originating entity to track
+  --  * The /id/ attribute is used by the originating entity to track any
-  --    any response or error stanza that it might receive in relation to
+  --    response or error stanza that it might receive in relation to the
-  --    the generated stanza from another entity (such as an intermediate
+  --    generated stanza from another entity (such as an intermediate server or
-  --    server or the intended recipient).  It is up to the originating
+  --    the intended recipient).  It is up to the originating entity whether the
-  --    entity whether the value of the 'id' attribute is unique only
+  --    value of the 'id' attribute is unique only within its current stream or
-  --    within its current stream or unique globally.
+  --    unique globally.
   --
   --  * The /from/ attribute specifies the JID of the sender.
   --
-  --  * The /to/ attribute specifies the JID of the intended recipient
+  --  * The /to/ attribute specifies the JID of the intended recipient for the
-  --  for the stanza.
+  --    stanza.
   --
-  --  * The /type/ attribute specifies the purpose or context of the
+  --  * The /type/ attribute specifies the purpose or context of the message,
-  --    message, presence, or IQ stanza. The particular allowable values
+  --    presence, or IQ stanza. The particular allowable values for the 'type'
-  --    for the 'type' attribute vary depending on whether the stanza is
+  --    attribute vary depending on whether the stanza is a message, presence,
-  --    a message, presence, or IQ stanza.
+  --    or IQ stanza.
 
   -- ** Messages
   -- | The /message/ stanza is a /push/ mechanism whereby one entity pushes
@@ -97,10 +86,9 @@ module Network.XMPP
   , waitForMessageError
   , filterMessages
   -- ** Presence
-  -- | The /presence/ stanza is a specialized /broadcast/
+  -- | The /presence/ stanza is a specialized /broadcast/ or /publish-subscribe/
-  -- or /publish-subscribe/ mechanism, whereby multiple entities
+  -- mechanism, whereby multiple entities receive information about an entity to
-  -- receive information about an entity to which they have
+  -- which they have subscribed.
-  -- subscribed.
   --
   -- <http://xmpp.org/rfcs/rfc6120.html#stanzas-semantics-presence>
   , Presence(..)
@@ -118,11 +106,10 @@ module Network.XMPP
   -- an entity to make a request of, and receive a response from, another
   -- entity. The data content and precise semantics  of the request and response
   -- is defined by the schema or other structural definition associated with the
-  -- XML namespace that
+  -- XML namespace that qualifies the direct child element of the IQ element. IQ
-  -- qualifies the direct child element of the IQ element. IQ interactions
+  -- interactions follow a common pattern of structured data exchange such as
-  -- follow a common pattern of structured data
+  -- get/result or set/result (although an error can be returned in reply to a
-  -- exchange such as get/result or set/result (although an error can be returned
+  -- request if appropriate)
-  -- in reply to a request if appropriate)
   --
   -- <http://xmpp.org/rfcs/rfc6120.html#stanzas-semantics-iq>
   , IQRequest(..)
@@ -176,4 +163,4 @@ auth username passwd resource = runErrorT $ do
         ErrorT $ xmppSASL username passwd
         res <- lift $ xmppBind resource
         lift $ xmppStartSession
-        return res
+        return res