From 170185fb7806ea89a9a723e88640bf0f048ca221 Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Thu, 17 Dec 2020 12:29:44 -0400 Subject: [PATCH] improve docs --- Types/Import.hs | 9 ++++++++- Types/Remote.hs | 11 ++++++----- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/Types/Import.hs b/Types/Import.hs index 0b136ca40b..2724ddc7ef 100644 --- a/Types/Import.hs +++ b/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) diff --git a/Types/Remote.hs b/Types/Remote.hs index 5e3e2308c3..2811f732ac 100644 --- a/Types/Remote.hs +++ b/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. --