More docs for UnstructuredNearest

docs/iris/src/whatsnew/contributions_1.12/newfeature_2017-Jan-09_unstructured_scheme.txt

@@ -0,0 +1,10 @@
+* a new regridding scheme, :class:`iris.analysis.UnstructuredNearest`,
+  performs nearest-neighbour regridding from unstructured onto "normal" grids.
+  Here, "unstructured" means that the data has X and Y coordinate values
+  defined at each horizontal location, instead of on independent X and Y
+  dimensions.
+  For example, data sampled on a trajectory or a tripolar ocean grid.
+
+  The essential purpose is the same as
+  :class:`iris.experimental.regrid.ProjectedUnstructuredNearest`.
+  This scheme, by comparison, is generally more accurate, but slower.

lib/iris/analysis/__init__.py

@@ -1,4 +1,4 @@
-# (C) British Crown Copyright 2010 - 2016, Met Office
+# (C) British Crown Copyright 2010 - 2017, Met Office
 #
 # This file is part of Iris.
 #
@@ -2369,6 +2369,14 @@ class UnstructuredNearest(object):
     .. Note::
         Currently only supports regridding, not interpolation.
 
+    .. Note::
+          This scheme performs essentially the same job as
+          :class:`iris.experimental.regrid.ProjectedUnstructuredNearest`.
+          That scheme is faster, but only works well on data in a limited
+          region of the globe, covered by a specified projection.
+          This approach is more rigorously correct and can be applied to global
+          datasets.
+
     """
     # Note: the argument requirements are simply those of the underlying
     # regridder class,

lib/iris/experimental/regrid.py

@@ -1692,6 +1692,12 @@ class ProjectedUnstructuredNearest(object):
     The source cube and the target cube will be projected into a common
     projection for the scipy calculation to be performed.
 
+    .. Note::
+          The :class:`iris.analysis.UnstructuredNearest` scheme performs
+          essentially the same job.  That calculation is more rigorously
+          correct and may be applied to larger data regions (including global).
+          This one however, where applicable, is substantially faster.
+
     """
     def __init__(self, projection=None):
         """