document what importKey returning Nothing does

That was added for thirdpartypopulated remotes, but for others it also
has the effect of skipping including the file in the imported tree.

diff --git a/Types/Remote.hs b/Types/Remote.hs
index 4e24329ecb0167f32b79cf065dcb8bc8c597a19f..e2a4940582ddd9819e16b27242d882faea6dcb24 100644 (file)
--- a/Types/Remote.hs
+++ b/Types/Remote.hs
@@ -307,10 +307,12 @@ data ImportActions a = ImportActions
        -- bearing in mind that the file on the remote may have changed
        -- since the ContentIdentifier was generated.
        --
+       -- When it returns nothing, the file at the ImportLocation 
+       -- not by included in the imported tree.
+       --
        -- When the remote is thirdPartyPopulated, this should check if the
        -- file stored on the remote is the content of an annex object,
-       -- and return its Key, or Nothing if it is not. Should not
-       -- otherwise return Nothing.
+       -- and return its Key, or Nothing if it is not.
        --
        -- Throws exception on failure to access the remote.
        , importKey :: Maybe (ImportLocation -> ContentIdentifier -> ByteSize -> MeterUpdate -> a (Maybe Key))

diff --git a/doc/design/external_special_remote_protocol/export_and_import_appendix.mdwn b/doc/design/external_special_remote_protocol/export_and_import_appendix.mdwn
index 9d474dbcbf6610ff1656ab9b548b53702f8e5842..24004402fe0eb93c00f50985ac5c60a7a8efa866 100644 (file)
--- a/doc/design/external_special_remote_protocol/export_and_import_appendix.mdwn
+++ b/doc/design/external_special_remote_protocol/export_and_import_appendix.mdwn
@@ -203,6 +203,8 @@ support a request, it can reply with `UNSUPPORTED-REQUEST`.
   ContentIdentifier specified by `EXPECTED`, or otherwise fail.  
   Replies:
   * `IMPORTKEY-SUCCESS Key`
+  * `IMPORTKEY-SKIP`  
+    This causes nothing to be imported for this file.
   * `IMPORTKEY-FAILURE ErrorMsg`
 * `RETRIEVEEXPORTEXPECTED File`  
   Retrieves the content of a file from the special remote