document Autosign symbol

1 files changed, 14 insertions, 6 deletions

diff --git a/KeyRing.hs b/KeyRing.hs
index 361d007..294933f 100644
--- a/KeyRing.hs
+++ b/KeyRing.hs
@@ -48,7 +48,6 @@ module KeyRing
     , KeyRingRuntime(..)
     , KeyDB
     , KeyData(..)
-    , UserIDRecord(..)
     , SubKey(..)
     , packet
     , locations
@@ -66,6 +65,7 @@ module KeyRing
     , matchpr
     , parseSpec
     , parseUID
+    , UserIDRecord(..)
     , pkcs8
     , RSAPublicKey(..)
     , rsaKeyFromPacket
@@ -215,6 +215,8 @@ data Access = AutoAccess -- ^ secret or public as appropriate based on existing
             | Sec        -- ^ secret information
             | Pub        -- ^ public information
 
+-- | Note that the documentation here is intended for when this value is
+-- assigned to 'fill'.  For other usage, see 'spill'.
 data KeyFilter = KF_None -- ^ No keys will be imported.
                | KF_Match String -- ^ Only the key that matches the spec will be imported.
                | KF_Subkeys   -- ^ Subkeys will be imported if their owner key is
@@ -344,7 +346,15 @@ data PassphraseSpec = PassphraseSpec
     -- ^ The passphrase will be read from this file or file descriptor.
     }
 
-data Transform = Autosign
+data Transform =
+        Autosign
+        -- ^ This operation will make signatures for any tor-style UID
+        -- that matches a tor subkey and thus can be authenticated without
+        -- requring the judgement of a human user.
+        --
+        -- A tor-style UID is one of the following form:
+        --
+        -- > Anonymous <root@HOSTNAME.onion>
  deriving (Eq,Ord)
 
 -- | This type describes an idempotent transformation (merge or import) on a
@@ -2550,10 +2560,8 @@ type SigAndTrust = ( MappedPacket
 type KeyKey = [ByteString]
 data SubKey = SubKey MappedPacket [SigAndTrust]
 
--- | This is a GPG Identity. It's poorly named
---   but we are keeping the name around until
---   we're sure we wont be cutting and pasting
---   code with master any more.
+-- | This is a GPG Identity which includes a master key and all its UIDs and
+-- subkeys and associated signatures.
 data KeyData = KeyData { keyMappedPacket :: MappedPacket    -- main key
                        , keySigAndTrusts :: [SigAndTrust]  -- sigs on main key
                        , keyUids :: (Map.Map String ([SigAndTrust],OriginMap))  -- uids