add descriptions for all remote config fields

not yet used

Annex/SpecialRemote/Config.hs

@@ -99,11 +99,15 @@ importTree = fromMaybe False . getRemoteConfigValue importTreeField
 commonFieldParsers :: [RemoteConfigFieldParser]
 commonFieldParsers =
 	[ optionalStringParser nameField
-	, optionalStringParser sameasNameField
+		(FieldDesc "name for the special remote")
-	, optionalStringParser sameasUUIDField
+	, optionalStringParser sameasNameField HiddenField
+	, optionalStringParser sameasUUIDField HiddenField
 	, optionalStringParser typeField
+		(FieldDesc "type of special remote")
 	, trueFalseParser autoEnableField False
+		(FieldDesc "automatically enable special remote")
 	, optionalStringParser preferreddirField
+		(FieldDesc "directory whose content is preferred")
 	]
 
 {- A remote with sameas-uuid set will inherit these values from the config
@@ -204,26 +208,39 @@ parseRemoteConfig c rpc =
 	notaccepted (Proposed _) = True
 	notaccepted (Accepted _) = False
 
-optionalStringParser :: RemoteConfigField -> RemoteConfigFieldParser
+optionalStringParser :: RemoteConfigField -> FieldDesc -> RemoteConfigFieldParser
-optionalStringParser f = RemoteConfigFieldParser f p
+optionalStringParser f fielddesc = RemoteConfigFieldParser
+	{ parserForField = f 
+	, valueParser = p
+	, fieldDesc = fielddesc
+	, valueDesc = Nothing
+	}
   where
 	p (Just v) _c = Right (Just (RemoteConfigValue (fromProposedAccepted v)))
 	p Nothing _c = Right Nothing
 
-yesNoParser :: RemoteConfigField -> Bool -> RemoteConfigFieldParser
+yesNoParser :: RemoteConfigField -> Bool -> FieldDesc -> RemoteConfigFieldParser
-yesNoParser = genParser yesNo "yes or no"
+yesNoParser f v fd = genParser yesNo f v fd
+	(Just (ValueDesc "yes or no"))
 
-trueFalseParser :: RemoteConfigField -> Bool -> RemoteConfigFieldParser
+trueFalseParser :: RemoteConfigField -> Bool -> FieldDesc -> RemoteConfigFieldParser
-trueFalseParser = genParser Git.Config.isTrueFalse "true or false"
+trueFalseParser f v fd = genParser Git.Config.isTrueFalse f v fd
+	(Just (ValueDesc "true or false"))
 
 genParser
 	:: Typeable t
 	=> (String -> Maybe t)
-	-> String -- ^ description of the value
 	-> RemoteConfigField
 	-> t -- ^ fallback value
+	-> FieldDesc
+	-> Maybe ValueDesc
 	-> RemoteConfigFieldParser
-genParser parse desc f fallback = RemoteConfigFieldParser f p
+genParser parse f fallback fielddesc valuedesc = RemoteConfigFieldParser	
+	{ parserForField = f
+	, valueParser = p
+	, fieldDesc = fielddesc
+	, valueDesc = valuedesc
+	}
   where
 	p Nothing _c = Right (Just (RemoteConfigValue fallback))
 	p (Just v) _c = case parse (fromProposedAccepted v) of
@@ -232,4 +249,7 @@ genParser parse desc f fallback = RemoteConfigFieldParser f p
 			Accepted _ -> Right (Just (RemoteConfigValue fallback))
 			Proposed _ -> Left $
 				"Bad value for " ++ fromProposedAccepted f ++
-				" (expected " ++ desc ++ ")"
+				case valuedesc of
+					Just (ValueDesc vd) ->
+						" (expected " ++ vd ++ ")"
+					Nothing -> ""

Remote/Adb.hs

@@ -39,7 +39,9 @@ remote = specialRemoteType $ RemoteType
 	, generate = gen
 	, configParser = mkRemoteConfigParser
 		[ optionalStringParser androiddirectoryField
+			(FieldDesc "location on the Android device where the files are stored")
 		, optionalStringParser androidserialField
+			(FieldDesc "sometimes needed to specify which Android device to use")
 		]
 	, setup = adbSetup
 	, exportSupported = exportIsSupported

Remote/Bup.hs

@@ -44,7 +44,9 @@ remote = specialRemoteType $ RemoteType
 	, enumerate = const (findSpecialRemotes "buprepo")
 	, generate = gen
 	, configParser = mkRemoteConfigParser
-		[optionalStringParser buprepoField]
+		[ optionalStringParser buprepoField
+			(FieldDesc "(required) bup repository to use")
+		]
 	, setup = bupSetup
 	, exportSupported = exportUnsupported
 	, importSupported = importUnsupported

Remote/Ddar.hs

@@ -37,7 +37,9 @@ remote = specialRemoteType $ RemoteType
 	, enumerate = const (findSpecialRemotes "ddarrepo")
 	, generate = gen
 	, configParser = mkRemoteConfigParser
-		[optionalStringParser ddarrepoField]
+		[ optionalStringParser ddarrepoField
+			(FieldDesc "(required) location of ddar archive to use")
+		]
 	, setup = ddarSetup
 	, exportSupported = exportUnsupported
 	, importSupported = importUnsupported

Remote/Directory.hs

@@ -43,7 +43,9 @@ remote = specialRemoteType $ RemoteType
 	, enumerate = const (findSpecialRemotes "directory")
 	, generate = gen
 	, configParser = mkRemoteConfigParser
-		[optionalStringParser directoryField]
+		[ optionalStringParser directoryField
+			(FieldDesc "(required) where the special remote stores data")
+		]
 	, setup = directorySetup
 	, exportSupported = exportIsSupported
 	, importSupported = importIsSupported

Remote/External.hs

@@ -788,7 +788,9 @@ lenientRemoteConfigParser = addRemoteConfigParser specialRemoteConfigParsers $
 	RemoteConfigParser
 		{ remoteConfigFieldParsers =
 			[ optionalStringParser externaltypeField
+				(FieldDesc "type of external special remote to use")
 			, trueFalseParser readonlyField False
+				(FieldDesc "enable readonly mode")
 			]
 		, remoteConfigRestPassthrough = const True
 		}

Remote/GCrypt.hs

@@ -68,7 +68,9 @@ remote = specialRemoteType $ RemoteType
 	, generate = gen
 	, configParser = mkRemoteConfigParser $
 		Remote.Rsync.rsyncRemoteConfigs ++
-		[ optionalStringParser gitRepoField ]
+		[ optionalStringParser gitRepoField
+			(FieldDesc "(required) path or url to gcrypt repository")
+		]
 	, setup = gCryptSetup
 	, exportSupported = exportUnsupported
 	, importSupported = importUnsupported

Remote/Git.hs

@@ -81,7 +81,9 @@ remote = RemoteType
 	, enumerate = list
 	, generate = gen
 	, configParser = mkRemoteConfigParser
-		[optionalStringParser locationField]
+		[ optionalStringParser locationField
+			(FieldDesc "url of git remote to remember with special remote")
+		]
 	, setup = gitSetup
 	, exportSupported = exportUnsupported
 	, importSupported = importUnsupported

Remote/GitLFS.hs

@@ -61,7 +61,9 @@ remote = specialRemoteType $ RemoteType
 	, enumerate = const (return [])
 	, generate = gen
 	, configParser = mkRemoteConfigParser
-		[optionalStringParser urlField]
+		[ optionalStringParser urlField
+			(FieldDesc "url of git-lfs repository")
+		]
 	, setup = mySetup
 	, exportSupported = exportUnsupported
 	, importSupported = importUnsupported

Remote/Glacier.hs

@@ -38,9 +38,12 @@ remote = specialRemoteType $ RemoteType
 	, generate = gen
 	, configParser = mkRemoteConfigParser
 		[ optionalStringParser datacenterField
+			(FieldDesc "S3 datacenter to use")
 		, optionalStringParser vaultField
+			(FieldDesc "name to use for vault")
 		, optionalStringParser fileprefixField
-		, optionalStringParser AWS.s3credsField
+			(FieldDesc "prefix to add to filenames in the vault")
+		, optionalStringParser AWS.s3credsField HiddenField
 		]
 	, setup = glacierSetup
 	, exportSupported = exportUnsupported

Remote/Helper/Chunked.hs

@@ -52,8 +52,9 @@ noChunks _ = False
 
 chunkConfigParsers :: [RemoteConfigFieldParser]
 chunkConfigParsers =
-	[ optionalStringParser chunksizeField
+	[ optionalStringParser chunksizeField HiddenField -- deprecated
 	, optionalStringParser chunkField
+		(FieldDesc "size of chunks (eg, 1MiB)")
 	]
 
 getChunkConfig :: ParsedRemoteConfig -> ChunkConfig

Remote/Helper/Encryptable.hs

@@ -56,20 +56,21 @@ encryptionAlreadySetup = EncryptionIsSetup
 encryptionConfigParsers :: [RemoteConfigFieldParser]
 encryptionConfigParsers =
 	[ encryptionFieldParser
-	, optionalStringParser cipherField
+	, optionalStringParser cipherField HiddenField
-	, optionalStringParser cipherkeysField
+	, optionalStringParser cipherkeysField HiddenField
-	, optionalStringParser pubkeysField
+	, optionalStringParser pubkeysField HiddenField
 	, yesNoParser embedCredsField False
+		(FieldDesc "embed credentials into git repository")
 	, macFieldParser
 	, optionalStringParser (Accepted "keyid")
+		(FieldDesc "gpg key id")
 	, optionalStringParser (Accepted "keyid+")
+		(FieldDesc "add additional gpg key")
 	, optionalStringParser (Accepted "keyid-")
+		(FieldDesc "remove gpg key")
 	, highRandomQualityFieldParser
 	]
 
-highRandomQualityField :: RemoteConfigField
-highRandomQualityField = Accepted "highRandomQuality"
-
 encryptionConfigs :: S.Set RemoteConfigField
 encryptionConfigs = S.fromList (map parserForField encryptionConfigParsers)
 
@@ -84,30 +85,47 @@ encryptionFieldParser = RemoteConfigFieldParser
 	{ parserForField = encryptionField
 	, valueParser = \v c -> Just . RemoteConfigValue
 		<$> parseEncryptionMethod (fmap fromProposedAccepted v) c
+	, fieldDesc = FieldDesc "how to encrypt data stored in the special remote"
+	, valueDesc = Just $ ValueDesc $
+		intercalate " or " (M.keys encryptionMethods)
 	}
 
+encryptionMethods :: M.Map String EncryptionMethod
+encryptionMethods = M.fromList
+	[ ("none", NoneEncryption)
+	, ("shared", SharedEncryption)
+	, ("hybrid", HybridEncryption)
+	, ("pubkey", PubKeyEncryption)
+	, ("sharedpubkey", SharedPubKeyEncryption)
+	]
+
 parseEncryptionMethod :: Maybe String -> RemoteConfig -> Either String EncryptionMethod
-parseEncryptionMethod (Just "none") _ = Right NoneEncryption
+parseEncryptionMethod (Just s) _ = case M.lookup s encryptionMethods of
-parseEncryptionMethod (Just "shared") _ = Right SharedEncryption
+	Just em -> Right em
-parseEncryptionMethod (Just "hybrid") _ = Right HybridEncryption
+	Nothing -> Left badEncryptionMethod
-parseEncryptionMethod (Just "pubkey") _ = Right PubKeyEncryption
-parseEncryptionMethod (Just "sharedpubkey") _ = Right SharedPubKeyEncryption
 -- Hybrid encryption is the default when a keyid is specified without
 -- an encryption field, or when there's a cipher already but no encryption
 -- field.
 parseEncryptionMethod Nothing c
 	| M.member (Accepted "keyid") c || M.member cipherField c = Right HybridEncryption
-parseEncryptionMethod _ _ = 
+	| otherwise = Left badEncryptionMethod
-	Left $ "Specify " ++ intercalate " or "
+
-		(map ((fromProposedAccepted encryptionField ++ "=") ++)
+badEncryptionMethod :: String
-		["none","shared","hybrid","pubkey", "sharedpubkey"])
+badEncryptionMethod = "Specify " ++ intercalate " or "
-		++ "."
+	(map ((fromProposedAccepted encryptionField ++ "=") ++)
+		(M.keys encryptionMethods))
+	++ "."
+
+highRandomQualityField :: RemoteConfigField
+highRandomQualityField = Accepted "highRandomQuality"
 
 highRandomQualityFieldParser :: RemoteConfigFieldParser
 highRandomQualityFieldParser = RemoteConfigFieldParser
 	{ parserForField = highRandomQualityField
 	, valueParser = \v _c -> Just . RemoteConfigValue
 		<$> parseHighRandomQuality (fmap fromProposedAccepted v)
+	, fieldDesc = HiddenField
+	, valueDesc = Nothing
 	}
  
 parseHighRandomQuality :: Maybe String -> Either String Bool
@@ -120,6 +138,9 @@ macFieldParser :: RemoteConfigFieldParser
 macFieldParser = RemoteConfigFieldParser
 	{ parserForField = macField
 	, valueParser = \v _c -> Just . RemoteConfigValue <$> parseMac v
+	, fieldDesc = FieldDesc "how to encrypt filenames used on the remote"
+	, valueDesc = Just $ ValueDesc $
+		intercalate " or " (M.keys macMap)
 	}
 
 parseMac :: Maybe (ProposedAccepted String) -> Either String Mac

Remote/Helper/ExportImport.hs

@@ -106,7 +106,9 @@ adjustExportImportRemoteType rt = rt
 exportImportConfigParsers :: [RemoteConfigFieldParser]
 exportImportConfigParsers =
 	[ yesNoParser exportTreeField False
+		(FieldDesc "export trees of files to this remote")
 	, yesNoParser importTreeField False
+		(FieldDesc "import trees of files from this remote")
 	]
 
 -- | Adjust a remote to support exporttree=yes and importree=yes.

Remote/Hook.hs

@@ -34,7 +34,9 @@ remote = specialRemoteType $ RemoteType
 	, enumerate = const (findSpecialRemotes "hooktype")
 	, generate = gen
 	, configParser = mkRemoteConfigParser
-		[optionalStringParser hooktypeField]
+		[ optionalStringParser hooktypeField
+			(FieldDesc "(required) specify collection of hooks to use")
+		]
 	, setup = hookSetup
 	, exportSupported = exportUnsupported
 	, importSupported = importUnsupported

Remote/Rsync.hs

@@ -54,6 +54,7 @@ remote = specialRemoteType $ RemoteType
 	, generate = gen
 	, configParser = mkRemoteConfigParser $ rsyncRemoteConfigs ++
 		[ optionalStringParser rsyncUrlField
+			(FieldDesc "(required) url or hostname:/directory for rsync to use")
 		]
 	, setup = rsyncSetup
 	, exportSupported = exportIsSupported
@@ -127,6 +128,7 @@ gen r u c gc rs = do
 rsyncRemoteConfigs :: [RemoteConfigFieldParser]
 rsyncRemoteConfigs = 
 	[ yesNoParser shellEscapeField True
+		(FieldDesc "avoid usual shell escaping (not recommended)")
 	]
 
 genRsyncOpts :: ParsedRemoteConfig -> RemoteGitConfig -> Annex [CommandParam] -> RsyncUrl -> RsyncOpts

Remote/S3.hs

@@ -76,19 +76,31 @@ remote = specialRemoteType $ RemoteType
 	, configParser = const $ pure $ RemoteConfigParser
 		{ remoteConfigFieldParsers = 
 			[ optionalStringParser bucketField
+				(FieldDesc "name of bucket to store content in")
 			, optionalStringParser hostField
+				(FieldDesc "S3 server hostname (default is Amazon S3)")
 			, optionalStringParser datacenterField
+				(FieldDesc "S3 datacenter to use (US, EU, us-west-1, ..)")
 			, optionalStringParser partsizeField
+				(FieldDesc "part size for multipart upload (eg 1GiB)")
 			, optionalStringParser storageclassField
+				(FieldDesc "storage class, eg STANDARD or REDUCED_REDUNDANCY")
 			, optionalStringParser fileprefixField
+				(FieldDesc "prefix to add to filenames in the bucket")
 			, yesNoParser versioningField False
+				(FieldDesc "enable versioning of bucket content")
 			, yesNoParser publicField False
+				(FieldDesc "allow public read access to the buckey")
 			, optionalStringParser publicurlField
+				(FieldDesc "url that can be used by public to download files")
 			, optionalStringParser protocolField
+				(FieldDesc "http or https")
 			, optionalStringParser portField
+				(FieldDesc "port to connect to")
 			, optionalStringParser requeststyleField
-			, optionalStringParser mungekeysField
+				(FieldDesc "for path-style requests, set to \"path\"")
-			, optionalStringParser AWS.s3credsField
+			, optionalStringParser mungekeysField HiddenField
+			, optionalStringParser AWS.s3credsField HiddenField
 			]
 		, remoteConfigRestPassthrough = \f ->
 			isMetaHeader f || isArchiveMetaHeader f

Remote/Tahoe.hs

@@ -60,7 +60,8 @@ remote = specialRemoteType $ RemoteType
 	, generate = gen
 	, configParser = mkRemoteConfigParser
 		[ optionalStringParser scsField
-		, optionalStringParser furlField
+			(FieldDesc "optional, normally a unique one is generated")
+		, optionalStringParser furlField HiddenField
 		]
 	, setup = tahoeSetup
 	, exportSupported = exportUnsupported

Remote/WebDAV.hs

@@ -49,7 +49,8 @@ remote = specialRemoteType $ RemoteType
 	, generate = gen
 	, configParser = mkRemoteConfigParser
 		[ optionalStringParser urlField
-		, optionalStringParser davcredsField
+			(FieldDesc "(required) url to the WebDAV directory")
+		, optionalStringParser davcredsField HiddenField
 		]
 	, setup = webdavSetup
 	, exportSupported = exportIsSupported

Types/Crypto.hs

@@ -15,6 +15,7 @@ module Types.Crypto (
 	Mac(..),
 	readMac,
 	showMac,
+	macMap,
 	defaultMac,
 	calcMac,
 ) where
@@ -23,6 +24,7 @@ import Utility.Hash
 import Utility.Gpg (KeyIds(..))
 
 import Data.Typeable
+import qualified Data.Map as M
 
 data EncryptionMethod
 	= NoneEncryption
@@ -61,9 +63,13 @@ showMac HmacSha512 = "HMACSHA512"
 
 -- Read the MAC algorithm from the remote config.
 readMac :: String -> Maybe Mac
-readMac "HMACSHA1"   = Just HmacSha1
+readMac n = M.lookup n macMap
-readMac "HMACSHA224" = Just HmacSha224
+
-readMac "HMACSHA256" = Just HmacSha256
+macMap :: M.Map String Mac
-readMac "HMACSHA384" = Just HmacSha384
+macMap = M.fromList
-readMac "HMACSHA512" = Just HmacSha512
+	[ ("HMACSHA1", HmacSha1)
-readMac _ = Nothing
+	, ("HMACSHA224", HmacSha224)
+	, ("HMACSHA256", HmacSha256)
+	, ("HMACSHA384", HmacSha384)
+	, ("HMACSHA512", HmacSha512)
+	]

Types/RemoteConfig.hs

@@ -41,10 +41,16 @@ data RemoteConfigValue where
 data RemoteConfigFieldParser = RemoteConfigFieldParser
 	{ parserForField :: RemoteConfigField
 	, valueParser :: Maybe (ProposedAccepted String) -> RemoteConfig -> Either String (Maybe RemoteConfigValue)
-	--, fieldDesc :: String
+	, fieldDesc :: FieldDesc
-	--, valueExample :: String
+	, valueDesc :: Maybe ValueDesc
 	}
 
+data FieldDesc
+	= FieldDesc String
+	| HiddenField
+
+newtype ValueDesc = ValueDesc String
+
 data RemoteConfigParser = RemoteConfigParser
 	{ remoteConfigFieldParsers :: [RemoteConfigFieldParser]
 	, remoteConfigRestPassthrough :: RemoteConfigField -> Bool