Haddock edits and removed some exports related to the now-removed

kImports interface.

1 files changed, 51 insertions, 28 deletions

diff --git a/KeyRing.hs b/KeyRing.hs
index 7fe031c..361d007 100644
--- a/KeyRing.hs
+++ b/KeyRing.hs
@@ -5,12 +5,15 @@
 -- 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.
+-- 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.
 --
+-- Typically, a client to this module would prepare a 'KeyRingOperation'
+-- describing what he wants done, and then invoke 'runKeyRing' to make it
+-- happen.
 {-# LANGUAGE CPP #-}
 {-# LANGUAGE TupleSections #-}
 {-# LANGUAGE ViewPatterns #-}
@@ -25,28 +28,32 @@ module KeyRing
       KikiResult(..)
     , KikiCondition(..)
     , KikiReportAction(..)
+    , errorString
+    , reportString
     -- * Manipulating Keyrings
     , runKeyRing
     , KeyRingOperation(..)
-    , StreamInfo(..)
     , PassphraseSpec(..)
     , Transform(..)
+    , PacketUpdate(..)
+    , noManip
+    , guardAuthentic
+    -- * Describing File Operations
+    , StreamInfo(..)
     , Access(..)
+    , FileType(..)
+    , InputFile(..)
     , KeyFilter(..)
-    , errorString
-    , reportString
+    -- * Results of a KeyRing Operation
     , KeyRingRuntime(..)
-    , InputFile(..)
-    , FileType(..)
-    , importPublic
-    , importSecret
-    , subkeysOnly
-    , PacketUpdate(..)
-    , noManip
     , KeyDB
     , KeyData(..)
+    , UserIDRecord(..)
     , SubKey(..)
     , packet
+    , locations
+    , keyflags
+    -- * Miscelaneous Utilities
     , isKey
     , derRSA
     , derToBase32
@@ -54,11 +61,8 @@ module KeyRing
     , filterMatches
     , flattenKeys
     , flattenTop
-    , guardAuthentic
     , Hosts.Hosts
     , isCryptoCoinKey
-    , keyflags
-    , locations
     , matchpr
     , parseSpec
     , parseUID
@@ -68,7 +72,6 @@ module KeyRing
     , secretToPublic
     , selectPublicKey
     , selectSecretKey
-    , UserIDRecord(..)
     , usage
     , usageString
     , walletImportFormat
@@ -204,6 +207,10 @@ data FileType = KeyRingFile (Maybe PasswordFile)
               | WalletFile -- (Maybe UsageTag)
               | Hosts
 
+-- | Use this type to indicate whether a file of type 'KeyRingFile' is expected
+-- to contain secret or public PGP key packets.  Note that it is not supported
+-- to mix both in the same file and that the secret key packets include all of
+-- the information contained in their corresponding public key packets.
 data Access = AutoAccess -- ^ secret or public as appropriate based on existing content
             | Sec        -- ^ secret information
             | Pub        -- ^ public information
@@ -218,8 +225,7 @@ data KeyFilter = KF_None -- ^ No keys will be imported.
                | KF_All -- ^ All keys will be imported.
 
 -- | This type describes how 'runKeyRing' will treat a file.
-data StreamInfo = StreamInfo
-    { access :: Access
+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.
@@ -242,25 +248,29 @@ data StreamInfo = StreamInfo
     --
     --  * '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.
+    --  * '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)
+    -- 'WalletFile':
+    --
+    --  * The 'spill' setting is ignored and the file's contents are shared.
+    --  (TODO)
+    --
+    -- 'Hosts': 
     --
-    -- 'Hosts': The 'spill' setting is ignored and the file's
-    --          contents are shared. (TODO)
+    --  * 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.
+    -- interpretted as a shell command that may be used to create the key if
+    -- it does not exist.
     , transforms :: [Transform] 
     -- ^ 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.
+    -- transformations that occur before the contents of a file are spilled
+    -- into the common pool.
     }
 
 
@@ -294,11 +304,24 @@ usageFromFilter _                = mzero
 
 data KeyRingRuntime = KeyRingRuntime
                         { rtPubring :: FilePath
+                        -- ^ Path to the file represented by 'HomePub'
                         , rtSecring :: FilePath
+                        -- ^ Path to the file represented by 'HomeSec'
                         , rtGrip :: Maybe String
+                        -- ^ Fingerprint or portion of a fingerprint used
+                        -- to identify the working GnuPG identity used to
+                        -- make signatures.
                         , rtWorkingKey :: Maybe Packet
+                        -- ^ The master key of the working GnuPG identity.
                         , rtKeyDB :: KeyDB
+                        -- ^ The common information pool where files spilled
+                        -- their content and from which they received new
+                        -- content.
                         , rtRingAccess :: Map.Map FilePath Access
+                        -- ^ The 'Access' values used for files of type
+                        -- 'KeyRingFile'.  If 'AutoAccess' was specified
+                        -- for a file, this 'Map.Map' will indicate the
+                        -- detected value that was used by the algorithm.
                         }
 
 -- | TODO: Packet Update should have deletion action