add mesh public doc-strings

lib/iris/common/metadata.py

@@ -1354,47 +1354,50 @@ def metadata_filter(
 ):
     """
     Filter a collection of objects by their metadata to fit the given metadata
-    criteria. Criteria can be one or both of: specific properties / other objects
-    carrying metadata to be matched.
+    criteria.
+
+    Criteria can be either specific properties or other objects with metadata
+    to be matched.
 
     Args:
 
-    * instances
+    * instances:
         One or more objects to be filtered.
 
     Kwargs:
 
-    * item
-        Either
-
-        (a) a :attr:`standard_name`, :attr:`long_name`, or
-        :attr:`var_name`. Defaults to value of `default`
-        (which itself defaults to `unknown`) as defined in
-        :class:`~iris.common.CFVariableMixin`.
-
-        (b) a 'coordinate' instance with metadata equal to that of
-        the desired coordinates. Accepts either a
-        :class:`~iris.coords.DimCoord`, :class:`~iris.coords.AuxCoord`,
-        :class:`~iris.aux_factory.AuxCoordFactory`,
-        :class:`~iris.common.CoordMetadata` or
-        :class:`~iris.common.DimCoordMetadata` or
-        :class:`~iris.experimental.ugrid.ConnectivityMetadata`.
-    * standard_name
-        The CF standard name of the desired coordinate. If None, does not
-        check for standard name.
-    * long_name
-        An unconstrained description of the coordinate. If None, does not
-        check for long_name.
-    * var_name
-        The netCDF variable name of the desired coordinate. If None, does
-        not check for var_name.
-    * attributes
-        A dictionary of attributes desired on the coordinates. If None,
-        does not check for attributes.
-    * axis
-        The desired coordinate axis, see
-        :func:`~iris.util.guess_coord_axis`. If None, does not check for
-        axis. Accepts the values 'X', 'Y', 'Z' and 'T' (case-insensitive).
+    * item:
+        Either,
+
+        * a :attr:`~iris.common.mixin.CFVariableMixin.standard_name`,
+          :attr:`~iris.common.mixin.CFVariableMixin.long_name`, or
+          :attr:`~iris.common.mixin.CFVariableMixin.var_name` which is compared
+          against the :meth:`~iris.common.mixin.CFVariableMixin.name`.
+
+        * a coordinate or metadata instance equal to that of
+          the desired coordinates e.g., :class:`~iris.coords.DimCoord`
+          or :class:`CoordMetadata`.
+
+    * standard_name:
+        The CF standard name of the desired coordinate. If ``None``, does not
+        check for ``standard_name``.
+
+    * long_name:
+        An unconstrained description of the coordinate. If ``None``, does not
+        check for ``long_name``.
+
+    * var_name:
+        The netCDF variable name of the desired coordinate. If ``None``, does
+        not check for ``var_name``.
+
+    * attributes:
+        A dictionary of attributes desired on the coordinates. If ``None``,
+        does not check for ``attributes``.
+
+    * axis:
+        The desired coordinate axis, see :func:`~iris.util.guess_coord_axis`.
+        If ``None``, does not check for ``axis``. Accepts the values ``X``,
+        ``Y``, ``Z`` and ``T`` (case-insensitive).
 
     Returns:
         A list of the objects supplied in the ``instances`` argument, limited

lib/iris/coords.py

@@ -590,8 +590,7 @@ def xml_element(self, doc):
 
         Returns:
             The :class:`xml.dom.minidom.Element` that will describe this
-            :class:`_DimensionalMetadata`, and the dictionary of attributes
-            that require to be added to this element.
+            :class:`_DimensionalMetadata`.
 
         """
         # Create the XML element as the camelCaseEquivalent of the
@@ -2271,8 +2270,7 @@ def xml_element(self, doc):
 
         Returns:
             The :class:`xml.dom.minidom.Element` that will describe this
-            :class:`DimCoord`, and the dictionary of attributes that require
-            to be added to this element.
+            :class:`DimCoord`.
 
         """
         # Create the XML element as the camelCaseEquivalent of the

lib/iris/cube.py

@@ -1588,53 +1588,62 @@ def coords(
 
         Kwargs:
 
-        * name_or_coord
-            Either
+        * name_or_coord:
+            Either,
 
-            (a) a :attr:`standard_name`, :attr:`long_name`, or
-            :attr:`var_name`. Defaults to value of `default`
-            (which itself defaults to `unknown`) as defined in
-            :class:`iris.common.CFVariableMixin`.
+            * a :attr:`~iris.common.mixin.CFVariableMixin.standard_name`,
+              :attr:`~iris.common.mixin.CFVariableMixin.long_name`, or
+              :attr:`~iris.common.mixin.CFVariableMixin.var_name` which is
+              compared against the :class:`~iris.common.mixin.CFVariableMixin.name`.
 
-            (b) a coordinate instance with metadata equal to that of
-            the desired coordinates. Accepts either a
-            :class:`iris.coords.DimCoord`, :class:`iris.coords.AuxCoord`,
-            :class:`iris.aux_factory.AuxCoordFactory`,
-            :class:`iris.common.CoordMetadata` or
-            :class:`iris.common.DimCoordMetadata`.
-        * standard_name
-            The CF standard name of the desired coordinate. If None, does not
-            check for standard name.
-        * long_name
-            An unconstrained description of the coordinate. If None, does not
-            check for long_name.
-        * var_name
-            The netCDF variable name of the desired coordinate. If None, does
-            not check for var_name.
-        * attributes
-            A dictionary of attributes desired on the coordinates. If None,
-            does not check for attributes.
-        * axis
-            The desired coordinate axis, see
-            :func:`iris.util.guess_coord_axis`. If None, does not check for
-            axis. Accepts the values 'X', 'Y', 'Z' and 'T' (case-insensitive).
-        * contains_dimension
-            The desired coordinate contains the data dimension. If None, does
+            * a coordinate or metadata instance equal to that of the desired
+              coordinate e.g., :class:`~iris.coords.DimCoord` or
+              :class:`~iris.common.metadata.CoordMetadata`.
+
+        * standard_name:
+            The CF standard name of the desired coordinate. If ``None``, does not
+            check for ``standard name``.
+
+        * long_name:
+            An unconstrained description of the coordinate. If ``None``, does not
+            check for ``long_name``.
+
+        * var_name:
+            The netCDF variable name of the desired coordinate. If ``None``, does
+            not check for ``var_name``.
+
+        * attributes:
+            A dictionary of attributes desired on the coordinates. If ``None``,
+            does not check for ``attributes``.
+
+        * axis:
+            The desired coordinate axis, see :func:`iris.util.guess_coord_axis`.
+            If ``None``, does not check for ``axis``. Accepts the values ``X``,
+            ``Y``, ``Z`` and ``T`` (case-insensitive).
+
+        * contains_dimension:
+            The desired coordinate contains the data dimension. If ``None``, does
             not check for the dimension.
-        * dimensions
+
+        * dimensions:
             The exact data dimensions of the desired coordinate. Coordinates
-            with no data dimension can be found with an empty tuple or list
-            (i.e. ``()`` or ``[]``). If None, does not check for dimensions.
-        * coord_system
-            Whether the desired coordinates have coordinate systems equal to
-            the given coordinate system. If None, no check is done.
-        * dim_coords
-            Set to True to only return coordinates that are the cube's
-            dimension coordinates. Set to False to only return coordinates
-            that are the cube's auxiliary and derived coordinates. If None,
+            with no data dimension can be found with an empty ``tuple`` or
+            ``list`` i.e., ``()`` or ``[]``. If ``None``, does not check for
+            dimensions.
+
+        * coord_system:
+            Whether the desired coordinates have a coordinate system equal to
+            the given coordinate system. If ``None``, no check is done.
+
+        * dim_coords:
+            Set to ``True`` to only return coordinates that are the cube's
+            dimension coordinates. Set to ``False`` to only return coordinates
+            that are the cube's auxiliary and derived coordinates. If ``None``,
             returns all coordinates.
 
-        See also :meth:`Cube.coord()<iris.cube.Cube.coord>`.
+        .. seealso:
+
+            The :meth:`Cube.coord` method for matching exactly one coordinate.
 
         """
         coords_and_factories = []
@@ -1715,18 +1724,16 @@ def coord(
         dim_coords=None,
     ):
         """
-        Return a single coord given the same arguments as :meth:`Cube.coords`.
+        Return a single coordinate given the same arguments as :meth:`Cube.coords`.
 
         .. note::
 
-            If the arguments given do not result in precisely 1 coordinate
-            being matched, an :class:`iris.exceptions.CoordinateNotFoundError`
-            is raised.
+            If the arguments given do not result in **precisely one** coordinate,
+            then a :class:`~iris.exceptions.CoordinateNotFoundError` is raised.
 
         .. seealso::
 
-            :meth:`Cube.coords()<iris.cube.Cube.coords>` for full keyword
-            documentation.
+            :meth:`Cube.coords()` for full keyword documentation.
 
         """
         coords = self.coords(