From be0e20cbb8f904a5091f88f32f353b5abed5cb06 Mon Sep 17 00:00:00 2001
From: joe <joe@jerkface.net>
Date: Sat, 3 May 2014 01:14:12 -0400
Subject: more haddock

---
 KeyRing.hs | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/KeyRing.hs b/KeyRing.hs
index 513ebb0..f7ea780 100644
--- a/KeyRing.hs
+++ b/KeyRing.hs
@@ -31,6 +31,7 @@ module KeyRing
     , Access(..)
     , KeyFilter(..)
     , KeyRingOperation(..)
+    , PassphraseSpec(..)
     , errorString
     , reportString
     , KeyRingRuntime(..)
@@ -275,11 +276,16 @@ data PacketUpdate = InducerSignature String [SignatureSubpacket]
 noManip :: KeyRingRuntime -> KeyData -> [PacketUpdate]
 noManip _ _ = []
 
+-- | This type is used to indicate where to obtain passphrases.
 data PassphraseSpec = PassphraseSpec
     { passSpecRingFile :: Maybe FilePath
+    -- ^ If not Nothing, the passphrase is to be used for packets
+    -- from this file.
     , passSpecKeySpec :: Maybe String
-    -- ^ non-Nothing value reserved for future use (TODO).
+    -- ^ Non-Nothing value reserved for future use.
+    -- (TODO: Use this to implement per-key passphrase associations).
     , passSpecPassFile :: InputFile
+    -- ^ The passphrase will be read from this file or file descriptor.
     }
 
 data Transform = Autosign
@@ -467,6 +473,13 @@ instance Applicative KikiCondition where
                             Left err -> err
             Left err -> err
 
+-- | This type is used to describe events triggered by a 
+-- 'runKeyRing'.  In addition to normal feedback 
+-- (e.g. 'NewPacket'), it also may indicate non-fatal
+-- IO exceptions (e.g. FailedExternal).  Because a 'KeyRingOperation'
+-- may describe a very intricate multifaceted algorithm with many
+-- inputs and outputs, an operation may be partially (or even mostly)
+-- successful even when some aspect failed.
 data KikiReportAction =
         NewPacket String
         | MissingPacket String
@@ -505,8 +518,8 @@ data KikiResult a = KikiResult
     { kikiCondition :: KikiCondition a
     -- ^ The result or a fatal error condition.
     , kikiReport :: [ (FilePath, KikiReportAction) ]
-    -- ^ A list of non-fatal warning messages and the files
-    -- that triggered them.
+    -- ^ A list of non-fatal warnings and informational messages
+    -- along with the files that triggered them.
     }
 
 keyPacket :: KeyData -> Packet
-- 
cgit v1.2.3