improve docs

Types/Import.hs

@@ -31,7 +31,14 @@ fromImportLocation = fromExportLocation
 
 {- An identifier for content stored on a remote that has been imported into
  - the repository. It should be reasonably short since it is stored in the
- - git-annex branch. -}
+ - git-annex branch.
+ -
+ - Since other things than git-annex can modify files on import remotes,
+ - and git-annex then be used to import those modifications, the
+ - ContentIdentifier needs to change when a file gets changed in such a
+ - way. Device, inode, and size is one example of a good content
+ - identifier. Or a hash if the remote's interface exposes hashes.
+ -}
 newtype ContentIdentifier = ContentIdentifier S.ByteString
 	deriving (Eq, Ord, Show, Generic)
 

Types/Remote.hs

@@ -113,9 +113,9 @@ data RemoteA a = Remote
 	-- Some remotes can checkPresent without an expensive network
 	-- operation.
 	, checkPresentCheap :: Bool
-	-- Some remotes support export of trees.
+	-- Some remotes support export of trees of files.
 	, exportActions :: ExportActions a
-	-- Some remotes support import of trees.
+	-- Some remotes support import of trees of files.
 	, importActions :: ImportActions a
 	-- Some remotes can provide additional details for whereis.
 	, whereisKey :: Maybe (Key -> a [String])
@@ -277,8 +277,9 @@ data ImportActions a = ImportActions
 	-- May also find old versions of files that are still stored in the
 	-- remote.
 	{ listImportableContents :: a (Maybe (ImportableContents (ContentIdentifier, ByteSize)))
-	-- Imports a file from the remote, without downloading it,
-	-- by generating a Key (of any type).
+	-- Generates a Key (of any type) for the file stored on the
+	-- remote at the ImportLocation. Does not download the file
+	-- from the remote.
 	--
 	-- May update the progress meter if it needs to perform an
 	-- expensive operation, such as hashing a local file.
@@ -288,7 +289,7 @@ data ImportActions a = ImportActions
 	-- since the ContentIdentifier was generated.
 	--
 	-- Throws exception on failure.
-	, importKey :: Maybe (ExportLocation -> ContentIdentifier -> MeterUpdate -> a Key)
+	, importKey :: Maybe (ImportLocation -> ContentIdentifier -> MeterUpdate -> a Key)
 	-- Retrieves a file from the remote. Ensures that the file
 	-- it retrieves has the requested ContentIdentifier.
 	--