Review changes: docs improvements; docstrings for cubelist combine methods.

Author: pp-mo

docs/src/userguide/loading_iris_cubes.rst

@@ -17,9 +17,10 @@ into a single multidimensional cube.
 
 .. hint::
 
-    There are some hints at :class:`iris.CombineOptions` on how Iris works to load
-    fewer and larger cubes, along with user options that can aid in controlling the
-    process.
+    There are details at :class:`iris.CombineOptions` on how Iris works to load
+    fewer and larger cubes :  The :data:`iris.COMBINE_POLICY` object allows the user to
+    control how cubes are combined during the loading process.  See the documentation
+    of the :class:`iris.CombineOptions` class for details.
 
 The :py:func:`iris.load` function automatically recognises the format
 of the given files and attempts to produce Iris Cubes from their contents.

lib/iris/__init__.py

@@ -16,8 +16,13 @@
 The :func:`load` function provides a simple way to explore data from
 the interactive Python prompt. It will convert the source data into
 :class:`Cubes <iris.cube.Cube>`, and combine those cubes into
-higher-dimensional cubes where possible
-(for which, please see :class:`iris.CombineOptions`).
+higher-dimensional cubes where possible.
+
+.. note::
+
+    User control of the 'combine' process is provided via a specific
+    :class:`iris.CombineOptions` object called :data:`iris.COMBINE_POLICY`.
+    See the :class:`iris.CombineOptions` class for details.
 
 The :func:`load_cube` and :func:`load_cubes` functions are similar to
 :func:`load`, but they raise an exception if the number of cubes is not

lib/iris/_combine.py

@@ -39,9 +39,10 @@ class CombineOptions(threading.local):
 
     The individual configurable options are :
 
-    * ``equalise_cubes_kwargs`` = (dict)
+    * ``equalise_cubes_kwargs`` = (dict or None)
         Specifies keywords for an :func:`iris.util.equalise_cubes` call, to be applied
-        before any merge/concatenate step.
+        before any merge/concatenate step.  If ``None``, or empty, no equalisation step
+        is performed.
 
     * ``merge_concat_sequence`` = "m" / "c" / "cm" / "mc"
         Specifies whether to apply :meth:`~iris.cube.CubeList.merge`, or
@@ -361,6 +362,7 @@ def _combine_cubes(cubes: List[Cube], options: dict) -> CubeList:
 
     eq_args = options.get("equalise_cubes_kwargs", None)
     if eq_args:
+        # Skip missing (or empty) arg, as no effect : see `equalise_cubes`.
         from iris.util import equalise_cubes
 
         equalise_cubes(cubelist, **eq_args)

lib/iris/cube.py

@@ -638,11 +638,57 @@ def concatenate(
         )
 
     def combine(self, options: str | dict | None = None, **kwargs) -> CubeList:
+        """Combine cubes, as with :func:`iris.util.combine_cubes`.
+
+        Parameters
+        ----------
+        options : str or dict, optional
+            Either a standard "combine settings" name, i.e. one of the
+            :data:`iris.CombineOptions.SETTINGS_NAMES`, or a dictionary of
+            settings options, as described for :class:`~iris.CombineOptions`.
+            Defaults to the current :meth:`~iris.CombineOptions.settings` of the
+            :data:`iris.COMBINE_POLICY`.
+
+        kwargs : dict
+            Individual option setting values, i.e. values for keys named in
+            :data:`iris.CombineOptions.OPTION_KEYS`, as described for
+            :meth:`~iris.CombineOptions.set`.
+            These take precedence over those set by the `options` arg.
+
+        Returns
+        -------
+        :class:`CubeList`
+
+        """
         from iris.util import combine_cubes
 
         return combine_cubes(self, options, **kwargs)
 
     def combine_cube(self, options: str | dict | None = None, **kwargs) -> CubeList:
+        """Combine to a single cube, with :func:`iris.util.combine_cubes`.
+
+        As :meth:`combine`, but raises a ValueError if the result is not a single cube.
+
+        Parameters
+        ----------
+        options : str or dict, optional
+            Either a standard "combine settings" name, i.e. one of the
+            :data:`iris.CombineOptions.SETTINGS_NAMES`, or a dictionary of
+            settings options, as described for :class:`~iris.CombineOptions`.
+            Defaults to the current :meth:`~iris.CombineOptions.settings` of the
+            :data:`iris.COMBINE_POLICY`.
+
+        kwargs : dict
+            Individual option setting values, i.e. values for keys named in
+            :data:`iris.CombineOptions.OPTION_KEYS`, as described for
+            :meth:`~iris.CombineOptions.set`.
+            These take precedence over those set by the `options` arg.
+
+        Returns
+        -------
+        Cube
+
+        """
         result = self.combine(options, **kwargs)
         n_cubes = len(result)
         if n_cubes != 1: