some haddock foo

1 files changed, 31 insertions, 7 deletions

diff --git a/KeyRing.hs b/KeyRing.hs
index b1e23b4..513ebb0 100644
--- a/KeyRing.hs
+++ b/KeyRing.hs
@@ -1,3 +1,16 @@
+---------------------------------------------------------------------------
+-- |
+-- Module      :  KeyRing
+--
+-- Maintainer  :  joe@jerkface.net
+-- Stability   :  experimental
+--
+-- kiki is a command-line utility for manipulating GnuPG's keyring files.
+-- This module is the programmer-facing API it uses to do that.
+--
+-- Note: This is *not* a public facing API. I (the author) consider this
+-- library to be internal to kiki and subject to change at my whim.
+--
 {-# LANGUAGE CPP #-}
 {-# LANGUAGE TupleSections #-}
 {-# LANGUAGE ViewPatterns #-}
@@ -7,14 +20,17 @@
 {-# LANGUAGE NoPatternGuards #-}
 {-# LANGUAGE ForeignFunctionInterface #-}
 module KeyRing
-    ( runKeyRing
+    (
+    -- * Error Handling
+      KikiResult(..)
+    , KikiCondition(..)
+    , KikiReportAction(..)
+    -- * Manipulating Keyrings
+    , runKeyRing
     , StreamInfo(..)
     , Access(..)
     , KeyFilter(..)
     , KeyRingOperation(..)
-    , KikiResult(..)
-    , KikiCondition(..)
-    , KikiReportAction(..)
     , errorString
     , reportString
     , KeyRingRuntime(..)
@@ -424,6 +440,10 @@ instance ASN1Object RSAPrivateKey where
 
 
 
+-- | This type is used to indicate success or failure
+-- and in the case of success, return the computed object.
+-- The 'FunctorToMaybe' class is implemented to facilitate
+-- branching on failture.
 data KikiCondition a = KikiSuccess a
     | FailedToLock [FilePath]
     | BadPassphrase
@@ -480,9 +500,13 @@ errorString :: KikiCondition a -> String
 errorString (KikiSuccess {}) = "success"
 errorString e = uncamel . show $ fmap (const ()) e
 
+-- | Errors in kiki are indicated by the returning of this record.
 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.
     }
 
 keyPacket :: KeyData -> Packet
@@ -1927,13 +1951,13 @@ disjoint_fp ks = {- concatMap group2 $ -} transpose grouped
 getBindings ::
   [Packet]
   ->
-    ( [([Packet],[SignatureOver])] -- ^ other signatures with key sets
-                                   --   that were used for the verifications
+    ( [([Packet],[SignatureOver])] --  other signatures with key sets
+                                   --  that were used for the verifications
     , [(Word8,
        (Packet, Packet), -- (topkey,subkey)
        [String],         -- usage flags
        [SignatureSubpacket], -- hashed data
-       [Packet])] -- ^ binding signatures
+       [Packet])] -- binding signatures
     )
 getBindings pkts = (sigs,bindings)
  where