Documentation to protocol-generic Connection interface.

1 files changed, 30 insertions, 4 deletions

diff --git a/Connection.hs b/Connection.hs
index 58b4f4e5..fc4025eb 100644
--- a/Connection.hs
+++ b/Connection.hs
@@ -9,18 +9,24 @@ import qualified Data.Map as Map
 
 import PingMachine
 
+-- | This type indicates the current status of a connection.  The type
+-- parameter indicates protocol-specific status information.  To present
+-- information as a user-comprehensible string, use 'showStatus'.
 data Status status
     = Dormant
     | InProgress status
     | Established
  deriving (Show,Eq,Ord,Functor)
 
+-- | A policy indicates a desired connection status.
 data Policy
-    = RefusingToConnect
-    | OpenToConnect
-    | TryingToConnect
+    = RefusingToConnect -- ^ We desire no connection.
+    | OpenToConnect     -- ^ We will cooperate if a remote side initiates.
+    | TryingToConnect   -- ^ We desire to be connected.
  deriving (Eq,Ord,Show)
 
+-- | Read-only information obtained via the 'connections' interface to
+-- 'Manager'.
 data Connection status = Connection
     { connStatus    :: STM (Status status)
     , connPolicy    :: STM Policy
@@ -28,20 +34,40 @@ data Connection status = Connection
     }
  deriving Functor
 
+-- | This is an interface to make or query status information about connections
+-- of a specific kind.
+--
+-- Type parameters:
+--
+--    /k/ names a connection.  It should implement Ord, and can be parsed and
+--    displayed using 'stringToKey' and 'showKey'.
+--
+--    /status/ indicates the progress of a connection.  It is intended as a
+--    parameter to the 'InProgress' constructor of 'Status'.
+--
 data Manager status k = Manager
-    { setPolicy    :: k -> Policy -> IO ()
+    { -- | Connect or disconnect a connection.
+      setPolicy    :: k -> Policy -> IO ()
+      -- | Obtain a list (in Map form) of all possible connections, whether
+      -- connected or not.
     , connections  :: STM (Map k (Connection status))
+      -- | Parse a connection key out of a string.  Inverse of 'showKey'.
     , stringToKey  :: String -> Maybe k
+      -- | Convert a progress value to a string.
     , showProgress :: status -> String
+      -- | Show a connection key as a string.
     , showKey      :: k -> String
     }
 
+-- | Present status information (visible in a UI) for a connection.
 showStatus :: Manager status k -> Status status -> String
 showStatus mgr Dormant        = "dormant"
 showStatus mgr Established    = "established"
 showStatus mgr (InProgress s) = "in progress ("++showProgress mgr s++")"
 
 
+-- | Combine two different species of 'Manager' into a single interface using
+-- 'Either' to combine key and status types.
 addManagers :: (Ord kA, Ord kB) =>
             Manager statusA kA
             -> Manager statusB kB