Some more doc

xcube/core/store/accessor.py

@@ -352,9 +352,17 @@ def preload_data(
     ) -> PreloadHandle:
         """Preload the given data items for faster access.
 
-        The method is blocking by default. You can pass a `monitor` to observe the
-        preload process, to cancel it, or to pass a function that is called if the
-        preload process successfully completed.
+        Warning: This is an experimental and potentially unstable API
+        introduced in xcube 1.8.
+
+        The method may be blocking or non-blocking.
+        Implementations may offer the following keyword arguments
+        in *preload_params*:
+
+        - ``blocking``: whether the preload process is blocking.
+          Should be `True` by default if supported.
+        - ``monitor``: a callback function that serves as a progress monitor.
+          It receives the preload handle and the recent partial state update.
 
         Args:
             data_ids: Data identifiers to be preloaded.

xcube/core/store/preload.py

@@ -237,20 +237,25 @@ def _run_preload_data(self, data_id: str) -> str:
         return data_id
 
     def _handle_preload_data_done(self, f: Future[str]):
+        # Find the data_id that belongs to given feature f
         data_id: str | None = None
         for data_id, future in self._futures.items():
             if f is future:
                 break
-        if data_id is None:
-            return
+        assert data_id is not None
         try:
             _value = f.result()
+            # No exceptions, notify everything seems ok
             self.notify(PreloadState(data_id, status=PreloadStatus.stopped))
         except CancelledError as e:
+            # Raised if future has been cancelled
+            # while executing `_run_preload_data`
             self.notify(
                 PreloadState(data_id, status=PreloadStatus.cancelled, exception=e)
             )
         except Exception as e:
+            # Raised if any exception occurred
+            # while executing `_run_preload_data`
             self.notify(PreloadState(data_id, status=PreloadStatus.failed, exception=e))
 
     def show(self) -> Any:

xcube/core/store/store.py

@@ -471,11 +471,6 @@ def get_preload_data_params_schema(self) -> JsonObjectSchema:
         """Get the JSON schema that describes the keyword
         arguments that can be passed to ``preload_data()``.
 
-        Refer to the ``DataPreloader`` interface for more information.
-
-        Warning: This is an experimental and potentially unstable API
-        introduced in xcube 1.8.
-
         Returns:
             A ``JsonObjectSchema`` object whose properties describe
             the parameters of ``preload_data()``.
@@ -493,7 +488,14 @@ def preload_data(
         Warning: This is an experimental and potentially unstable API
         introduced in xcube 1.8.
 
-        Refer to the ``DataPreloader`` interface for more information.
+        The method may be blocking or non-blocking.
+        Implementations may offer the following keyword arguments
+        in *preload_params*:
+
+        - ``blocking``: whether the preload process is blocking.
+          Should be `True` by default if supported.
+        - ``monitor``: a callback function that serves as a progress monitor.
+          It receives the preload handle and the recent partial state update.
 
         Args:
             data_ids: Data identifiers to be preloaded.
@@ -503,7 +505,7 @@ def preload_data(
 
         Returns:
             A handle for the preload process. The default implementation
-            returns an empty process handle.
+            returns an empty preload handle.
         """
         return NullPreloadHandle()