Deprecate regrids (#4548)

* Deprecations.

* Correct and clarify dosctrings for PointInCell.

* Remove reference from UnstructuredNearest to ProjectedUnstructuredNearest.

* Added whatsnew content.

* Tiny fix to deprecation docs.

* Fixes to whatsnew text.

* Move still-used code from experimental.regrid to analysis._area_weighted.

* Fix minor test problem.

* No iris.cube import in iris.analysis._area_weighted, to avoid circular import.

Author: pp-mo

docs/src/whatsnew/latest.rst

@@ -234,6 +234,12 @@ This document explains the changes made to Iris for this release
 #. `@pp-mo`_ deprecated :mod:`iris.experimental.regrid_conservative`.  This is
    now replaced by `iris-emsf-regrid`_.  (:pull:`4551`)
 
+#. `@pp-mo`_ deprecated everything in :mod:`iris.experimental.regrid`.
+   Most features have a preferred exact alternative, as suggested, *except*
+   :class:`iris.experimental.regrid.ProjectedUnstructuredLinear` : that has no
+   identical equivalent, but :class:`iris.analysis.UnstructuredNearest` is
+   suggested as being quite close (though possibly slower).  (:pull:`4548`)
+
 
 🔗 Dependencies
 ===============
@@ -289,6 +295,15 @@ This document explains the changes made to Iris for this release
    contributing to the docs <contributing.documentation_easy>` to the docs.
    (:pull:`4461`)
 
+#. `@pp-mo`_ improved and corrected docstrings of
+   :class:`iris.analysis.PointInCell`, making it clear what is the actual
+   calculation performed.  (:pull:`4548`)
+
+#. `@pp-mo`_ removed reference in docstring of
+   :class:`iris.analysis.UnstructuredNearest` to the obsolete (deprecated)
+   :class:`iris.experimental.regrid.ProjectedUnstructuredNearest`.
+   (:pull:`4548`)
+
 
 💼 Internal
 ===========

lib/iris/analysis/__init__.py

@@ -2691,14 +2691,6 @@ class UnstructuredNearest:
     .. 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
@@ -2769,6 +2761,9 @@ class PointInCell:
     This class describes the point-in-cell regridding scheme for use
     typically with :meth:`iris.cube.Cube.regrid()`.
 
+    Each result datapoint is an average over all source points that fall inside
+    that (bounded) target cell.
+
     The PointInCell regridder can regrid data from a source grid of any
     dimensionality and in any coordinate system.
     The location of each source point is specified by X and Y coordinates
@@ -2786,8 +2781,12 @@ class PointInCell:
 
     def __init__(self, weights=None):
         """
-        Point-in-cell regridding scheme suitable for regridding over one
-        or more orthogonal coordinates.
+        Point-in-cell regridding scheme suitable for regridding from a source
+        cube with X and Y coordinates all on the same dimensions, to a target
+        cube with bounded X and Y coordinates on separate X and Y dimensions.
+
+        Each result datapoint is an average over all source points that fall
+        inside that (bounded) target cell.
 
         Optional Args: