Review changes : documentation improvements.

SciTools · Oct 24, 2024 · 52c2fc4 · 52c2fc4
1 parent 954396a
commit 52c2fc4
Showing 1 changed file with 15 additions and 5 deletions.
diff --git a/lib/iris/__init__.py b/lib/iris/__init__.py
@@ -317,12 +317,22 @@ def _load_collection(uris, constraints=None, callback=None):
 class LoadPolicy(threading.local):
     """A container for loading strategy options.
 
-    Controls merge/concatenate usage, and the handling of cases where multiple reference
-    fields merge to define an additional dimension (e.g. a time-varying orography).
+    Controls merge/concatenate usage during loading.
+
+    Also controls the detection and handling of cases where a hybrid coordinate
+    uses multiple reference fields : for example, a UM file which contains a series of
+    fields describing time-varying orography.
 
     Options can be set directly, or via :meth:`~iris.LoadPolicy.set`, or changed for
     the scope of a code block with :meth:`~iris.LoadPolicy.context`.
 
+    .. note ::
+
+        The default behaviour will "fix" loading for cases like the one just described.
+        However this is not strictly backwards-compatible.  If this causes problems,
+        you can force identical loading behaviour to earlier Iris versions with
+        ``LOAD_POLICY.set("legacy")`` or equivalent.
+
     .. testsetup::
 
         from iris import LOAD_POLICY
@@ -528,10 +538,10 @@ def context(self, settings=None, **kwargs):
         0: x_wind / (m s-1)                    (time: 2; model_level_number: 5; latitude: 144; longitude: 192)
         1: x_wind / (m s-1)                    (time: 12; model_level_number: 5; latitude: 144; longitude: 192)
         2: x_wind / (m s-1)                    (model_level_number: 5; latitude: 144; longitude: 192)
-
+        >>>
         >>> with LOAD_POLICY.context("recommended"):
         ...     cubes = iris.load(path, "x_wind")
-        >>> cubes
+        >>> print(cubes)
         0: x_wind / (m s-1)                    (model_level_number: 5; time: 15; latitude: 144; longitude: 192)>
         """
         # Save the current state
@@ -546,7 +556,7 @@ def context(self, settings=None, **kwargs):
             self.set(saved_settings)
 
 
-#: Object containing file loading options.
+#: A control object containing the current file loading options.
 LOAD_POLICY = LoadPolicy("legacy")
 # The unique (singleton) policy object
 # N.B. FOR NOW, our starting point is "legacy" rather than "default"