cosmetics, haddock.

1 files changed, 77 insertions, 35 deletions

diff --git a/KeyRing.hs b/KeyRing.hs
index f7ea780..7fe031c 100644
--- a/KeyRing.hs
+++ b/KeyRing.hs
@@ -27,11 +27,12 @@ module KeyRing
     , KikiReportAction(..)
     -- * Manipulating Keyrings
     , runKeyRing
+    , KeyRingOperation(..)
     , StreamInfo(..)
+    , PassphraseSpec(..)
+    , Transform(..)
     , Access(..)
     , KeyFilter(..)
-    , KeyRingOperation(..)
-    , PassphraseSpec(..)
     , errorString
     , reportString
     , KeyRingRuntime(..)
@@ -198,7 +199,7 @@ type PasswordFile = InputFile
 
 data FileType = KeyRingFile (Maybe PasswordFile)
               -- ^ PasswordFile parameter is deprecated in favor
-              -- of kPassphrases. TODO: remove it.
+              -- of opPassphrases. TODO: remove it.
               | PEMFile
               | WalletFile -- (Maybe UsageTag)
               | Hosts
@@ -216,18 +217,50 @@ data KeyFilter = KF_None -- ^ No keys will be imported.
                               -- identity (signed or self-authenticating).
                | KF_All -- ^ All keys will be imported.
 
+-- | This type describes how 'runKeyRing' will treat a file.
 data StreamInfo = StreamInfo
     { access :: Access
+    -- ^ Indicates whether the file is allowed to contain secret information.
     , typ :: FileType
+    -- ^ Indicates the format and content type of the file.
     , fill :: KeyFilter
-    , spill :: KeyFilter -- ^ Currently respected for PEMFile and KeyRingFile.
-                         -- (TODO: WalletFile and Hosts)
-                         -- Note that this is currently treated as a boolean
-                         -- flag.  KF_None means the file is not spillable
-                         -- and anything else means that it is.
+    -- ^ This filter controls what packets will be inserted into a file.
+    , spill :: KeyFilter
+    --
+    -- ^ Use this to indicate whether or not a file's contents should be
+    -- available for updating other files.  Note that although its type is
+    -- 'KeyFilter', it is usually interpretted as a boolean flag.  Details
+    -- depend on 'typ' and are as follows:
+    --
+    -- 'KeyRingFile':
+    --
+    --  * 'KF_None' - The file's contents will not be shared.
+    --
+    --  * otherwise - The file's contents will be shared.
+    --
+    -- 'PEMFile':
+    --
+    --  * 'KF_None'  - The file's contents will not be shared.
+    --
+    --  * 'KF_Match' - The file's key will be shared with the specified
+    --                 owner key and usage tag.
+    --
+    --  * otherwise  - Unspecified.  Do not use.
+    --
+    -- 'WalletFile': The 'spill' setting is ignored and the file's
+    --               contents are shared. (TODO)
+    --
+    -- 'Hosts': The 'spill' setting is ignored and the file's
+    --          contents are shared. (TODO)
+    --
     , initializer :: Maybe String
+    -- ^ If 'typ' is 'PEMFile' and an 'initializer' string is set, then it is
+    -- interpretted as a shell command that may be used to create the key if it
+    -- does not exist.
     , transforms :: [Transform] 
-    -- ^ TODO: currently ignored
+    -- ^ Ignored.  TODO: The intention is that we may indicate per-file
+    -- transformations that occur before a file's contents are spilled into the
+    -- common pool.
     }
 
 
@@ -291,13 +324,22 @@ data PassphraseSpec = PassphraseSpec
 data Transform = Autosign
  deriving (Eq,Ord)
 
+-- | This type describes an idempotent transformation (merge or import) on a
+-- set of GnuPG keyrings and other key files.
 data KeyRingOperation = KeyRingOperation
-    { kFiles :: Map.Map InputFile StreamInfo
-    , kPassphrases :: [PassphraseSpec]
-    , kTransform :: [Transform]
+    { opFiles :: Map.Map InputFile StreamInfo
+    -- ^ Indicates files to be read or updated.
+    , opPassphrases :: [PassphraseSpec]
+    -- ^ Indicates files or file descriptors where passphrases can be found.
+    , opTransforms :: [Transform]
+    -- ^ Transformations to be performed on the key pool after all files have
+    -- been read and before any have been written.
     , kManip :: KeyRingRuntime -> KeyData -> [PacketUpdate]--[KeyRingAddress PacketUpdate]
-    -- ^ TODO: this is deprecated in favor of kTransform (remove it)
-    , homeSpec :: Maybe String
+    -- ^ This is deprecated in favor of opTransforms (TODO: remove it)
+    , opHome :: Maybe FilePath
+    -- ^ If provided, this is the directory where the 'HomeSec' and 'HomePub'
+    -- files reside.  Otherwise, the evironment variable $GNUPGHOME is consulted
+    -- and if that is not set, it falls back to $HOME/.gnupg.
     }
 
 resolveInputFile :: InputFileContext -> InputFile -> [FilePath]
@@ -321,7 +363,7 @@ resolveForReport mctx f = concat $ resolveInputFile ctx f
 filesToLock ::
   KeyRingOperation -> InputFileContext -> [FilePath]
 filesToLock k ctx = do
-    (f,stream) <- Map.toList (kFiles k)
+    (f,stream) <- Map.toList (opFiles k)
     case fill stream of
         KF_None -> []
         _       -> resolveInputFile ctx f
@@ -473,13 +515,12 @@ 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.
+-- | This type is used to describe events triggered by '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
@@ -1029,7 +1070,7 @@ mergeHostFiles krd db ctx = do
         ishosts Hosts = True
         ishosts _     = False
         files istyp = do
-            (f,stream) <- Map.toList (kFiles krd)
+            (f,stream) <- Map.toList (opFiles krd)
             guard (istyp $ typ stream)
             return f
 
@@ -1086,7 +1127,7 @@ writeHostsFiles krd ctx (hostdbs0,hostdbs,u1,gpgnames,outgoing_names) = do
         isMutableHosts (typ -> Hosts)    = True
         isMutableHosts _                 = False
         files istyp = do
-            (f,stream) <- Map.toList (kFiles krd)
+            (f,stream) <- Map.toList (opFiles krd)
             guard (istyp stream)
             return f -- resolveInputFile ctx f
 
@@ -1127,11 +1168,11 @@ buildKeyDB :: InputFileContext -> Maybe String -> KeyRingOperation
 buildKeyDB ctx grip0 keyring = do
     let 
         files isring = do
-            (f,stream) <- Map.toList (kFiles keyring)
+            (f,stream) <- Map.toList (opFiles keyring)
             guard (isring $ typ stream)
             resolveInputFile ctx f
 
-        (ringMap,nonRingMap) = Map.partition (isring . typ) $ kFiles keyring
+        (ringMap,nonRingMap) = Map.partition (isring . typ) $ opFiles keyring
 
         readp f stream = fmap readp0 $ readPacketsFromFile ctx f
          where
@@ -1207,7 +1248,7 @@ buildKeyDB ctx grip0 keyring = do
 
     -- PEM files
     let pems = do
-            (n,stream) <- Map.toList $ kFiles keyring
+            (n,stream) <- Map.toList $ opFiles keyring
             grip <- maybeToList grip
             n <- resolveInputFile ctx n
             guard $ spillable stream && ispem (typ stream)
@@ -1448,7 +1489,7 @@ writeWalletKeys krd db wk = do
         isMutableWallet (typ -> WalletFile {}) = True
         isMutableWallet _                      = False
         files pred = do
-            (f,stream) <- Map.toList (kFiles krd)
+            (f,stream) <- Map.toList (opFiles krd)
             guard (pred stream)
             resolveInputFile (InputFileContext "" "") f
     let writeWallet report n = do
@@ -1536,7 +1577,7 @@ writeRingKeys krd rt {- db wk secring pubring -} unspilled = do
         ctx = InputFileContext secring pubring
     let s = do
         (f,f0,stream) <- do
-            (f0,stream) <- Map.toList (kFiles krd)
+            (f0,stream) <- Map.toList (opFiles krd)
             guard (isring $ typ stream)
             f <- resolveInputFile ctx f0
             return (f,f0,stream)
@@ -1711,19 +1752,19 @@ makeMemoizingDecrypter operation ctx keys = do
     pws <-
         Traversable.mapM (cachedContents ctx . fromJust . pwfile . typ)
                          (Map.mapKeys (resolveForReport Nothing) -- see note (*) note above
-                            $ Map.filter (isJust . pwfile . typ) $ kFiles operation)
+                            $ Map.filter (isJust . pwfile . typ) $ opFiles operation)
     pws2 <- 
         Traversable.mapM (cachedContents ctx)
          $ Map.fromList $ mapMaybe
                 (\spec -> (,passSpecPassFile spec) `fmap` do
                     guard $ isNothing $ passSpecKeySpec spec
                     passSpecRingFile spec)
-                (kPassphrases operation)
+                (opPassphrases operation)
     defpw <- do
         Traversable.mapM (cachedContents ctx . passSpecPassFile)
          $ listToMaybe $ filter (\sp -> isNothing (passSpecRingFile sp)
                                         && isNothing (passSpecKeySpec sp))
-                                    $ kPassphrases operation
+                                    $ opPassphrases operation
     unkeysRef <- newIORef (Map.empty :: Map.Map KeyKey Packet)
     return $ doDecrypt unkeysRef (pws `Map.union` pws2) defpw
  where
@@ -1830,7 +1871,7 @@ initializeMissingPEMFiles ::
 initializeMissingPEMFiles operation ctx grip decrypt db = do
         nonexistents <-
            filterM (fmap not . doesFileExist . fst)
-               $ do (f,t) <- Map.toList (kFiles operation)
+               $ do (f,t) <- Map.toList (opFiles operation)
                     f <- resolveInputFile ctx f
                     return (f,t)
 
@@ -1897,7 +1938,7 @@ combineTransforms operation rt kd = updates
  where
     updates = kManip operation rt kd
                 ++ concatMap (\t -> resolveTransform t rt kd) sanitized
-    sanitized = group (sort (kTransform operation)) >>= take 1
+    sanitized = group (sort (opTransforms operation)) >>= take 1
 
 isSubkeySignature (SubkeySignature {}) = True
 isSubkeySignature _                    = False
@@ -2024,9 +2065,10 @@ resolveTransform Autosign rt kd@(KeyData k ksigs umap submap) = ops
                    gs = groupBy sameMaster (sortBy (comparing code) bindings')
 
 
+-- | Load and update key files according to the specified 'KeyRingOperation'.
 runKeyRing :: KeyRingOperation -> IO (KikiResult KeyRingRuntime)
 runKeyRing operation = do
-    homedir <- getHomeDir (homeSpec operation)
+    homedir <- getHomeDir (opHome operation)
     let try' :: KikiCondition a -> (a -> IO (KikiResult b)) -> IO (KikiResult b)
         -- FIXME: try' should probably accept a list of KikiReportActions.
         --  This would be useful for reporting on disk writes that have already