From 257d9b18a244f3b58275ab49ccbea9f421839642 Mon Sep 17 00:00:00 2001
From: Tremain Knight <2108488+tkknight@users.noreply.github.com>
Date: Thu, 25 Jan 2024 11:15:08 +0000
Subject: [PATCH] numpydocs

---
 lib/iris/_concatenate.py            | 12 ++---
 lib/iris/_data_manager.py           |  2 +-
 lib/iris/_lazy_data.py              |  8 ++--
 lib/iris/_merge.py                  | 18 ++++----
 lib/iris/analysis/_area_weighted.py |  2 +-
 lib/iris/analysis/_interpolation.py |  6 +--
 lib/iris/analysis/_regrid.py        |  8 ++--
 lib/iris/analysis/cartography.py    |  8 ++--
 lib/iris/analysis/geometry.py       | 13 +++---
 lib/iris/analysis/maths.py          | 70 ++++++++++++-----------------
 lib/iris/analysis/stats.py          |  2 +-
 lib/iris/analysis/trajectory.py     |  6 +--
 lib/iris/config.py                  | 12 ++---
 lib/iris/util.py                    | 33 ++++++--------
 14 files changed, 89 insertions(+), 111 deletions(-)

diff --git a/lib/iris/_concatenate.py b/lib/iris/_concatenate.py
index 214cfa00cc..ea2ba65402 100644
--- a/lib/iris/_concatenate.py
+++ b/lib/iris/_concatenate.py
@@ -488,7 +488,7 @@ def _coordinate_differences(self, other, attr, reason="metadata"):
         attr : str
             The _CubeSignature attribute within which differences exist
             between `self` and `other`.
-        reason : str
+        reason : str, default="metadata"
             The reason to give for mismatch (function is normally, but not
             always, testing metadata)
 
@@ -854,22 +854,22 @@ def register(
         axis : optional
             Seed the dimension of concatenation for the :class:`_ProtoCube`
             rather than rely on negotiation with source-cubes.
-        error_on_mismatch : bool, optional
+        error_on_mismatch : bool, default=False
             If True, raise an informative error if registration fails.
-        check_aux_coords : bool, optional
+        check_aux_coords : bool, default=False
             Checks if the points and bounds of auxiliary coordinates of the
             cubes match. This check is not applied to auxiliary coordinates
             that span the dimension the concatenation is occurring along.
             Defaults to False.
-        check_cell_measures : bool, optional
+        check_cell_measures : bool, default=False
             Checks if the data of cell measures of the cubes match. This check
             is not applied to cell measures that span the dimension the
             concatenation is occurring along. Defaults to False.
-        check_ancils : bool, optional
+        check_ancils : bool, default=False
             Checks if the data of ancillary variables of the cubes match. This
             check is not applied to ancillary variables that span the dimension
             the concatenation is occurring along. Defaults to False.
-        check_derived_coords : bool, optional
+        check_derived_coords : bool, default=False
             Checks if the points and bounds of derived coordinates of the cubes
             match. This check is not applied to derived coordinates that span
             the dimension the concatenation is occurring along. Note that
diff --git a/lib/iris/_data_manager.py b/lib/iris/_data_manager.py
index 6db1d16889..15dfbd0030 100644
--- a/lib/iris/_data_manager.py
+++ b/lib/iris/_data_manager.py
@@ -273,7 +273,7 @@ def copy(self, data=None):
 
         Parameters
         ----------
-        data :
+        data : optional
             Replace the data of the copy with this data.
 
         Returns
diff --git a/lib/iris/_lazy_data.py b/lib/iris/_lazy_data.py
index b430a4d682..2ab41ecb45 100644
--- a/lib/iris/_lazy_data.py
+++ b/lib/iris/_lazy_data.py
@@ -72,12 +72,12 @@ def _optimum_chunksize_internals(
         Pre-existing chunk shape of the target data.
     shape : tuple of int
         The full array shape of the target data.
-    limit : int
+    limit : int, optional
         The 'ideal' target chunk size, in bytes.  Default from
         :mod:`dask.config`.
     dtype : np.dtype
         Numpy dtype of target data.
-    dims_fixed : list of bool
+    dims_fixed : list of bool, optional
         If set, a list of values equal in length to 'chunks' or 'shape'.
         'True' values indicate a dimension that can not be changed, i.e. that
         element of the result must equal the corresponding value in 'chunks' or
@@ -232,14 +232,14 @@ def as_lazy_data(
         This will be converted to a :class:`dask.array.Array`.
     chunks : list of int, optional
         If present, a source chunk shape, e.g. for a chunked netcdf variable.
-    asarray : bool, optional
+    asarray : bool, default=False
         If True, then chunks will be converted to instances of `ndarray`.
         Set to False (default) to pass passed chunks through unchanged.
     dims_fixed : list of bool, optional
         If set, a list of values equal in length to 'chunks' or data.ndim.
         'True' values indicate a dimension which can not be changed, i.e. the
         result for that index must equal the value in 'chunks' or data.shape.
-    dask_chunking : bool, optional
+    dask_chunking : bool, default=False
         If True, Iris chunking optimisation will be bypassed, and dask's default
         chunking will be used instead. Including a value for chunks while dask_chunking
         is set to True will result in a failure.
diff --git a/lib/iris/_merge.py b/lib/iris/_merge.py
index 7705dd6bea..de36cb3aa1 100644
--- a/lib/iris/_merge.py
+++ b/lib/iris/_merge.py
@@ -68,7 +68,7 @@ class _CoordMetaData(
     bounds_dtype :
         The bounds data :class:`numpy.dtype` of an associated coordinate.
         None otherwise.
-    kwargs:
+    kwargs :
         A dictionary of key/value pairs required to create a coordinate.
 
     """
@@ -162,11 +162,11 @@ class _CoordPayload(namedtuple("CoordPayload", ["scalar", "vector", "factory_def
 
     Parameters
     ----------
-    scalar:
+    scalar :
         A :class:`_ScalarCoordPayload` instance.
-    vector:
+    vector :
         A :class:`_VectorCoordPayload` instance.
-    factory_defns:
+    factory_defns :
         A list of :class:`_FactoryDefn` instances.
 
     """
@@ -637,7 +637,7 @@ def _separable(name, indexes):
 
     Returns
     -------
-    tupl
+    tuple
         A tuple containing the set of separable and inseparable
         candidate dimensions.
 
@@ -777,7 +777,7 @@ def _is_dependent(dependent, independent, positions, function_mapping=None):
     positions :
         A list containing a dictionary of candidate dimension key to
         scalar value pairs for each source-cube.
-    function_mapping : optional, default=None
+    function_mapping : optional
         A dictionary that enumerates a valid functional relationship
         between the dependent candidate dimension and the independent
         candidate dimension/s.
@@ -1052,7 +1052,7 @@ def derive_space(groups, relation_matrix, positions, function_matrix=None):
     positions :
         A list containing a dictionary of candidate dimension key to
         scalar value pairs for each source-cube.
-    function_matrix : optional, default=None
+    function_matrix : optional
           The function mapping dictionary for each candidate dimension that
           participates in a functional relationship.
 
@@ -1186,7 +1186,7 @@ def merge(self, unique=True):
 
         Parameters
         ----------
-        unique :
+        unique : bool, default=True
             If True, raises `iris.exceptions.DuplicateDataError` if
             duplicate cubes are detected.
 
@@ -1294,7 +1294,7 @@ def register(self, cube, error_on_mismatch=False):
         cube :
             Candidate :class:`iris.cube.Cube` to be associated with
             this :class:`ProtoCube`.
-        error_on_mismatch :bool,  optional, default=False
+        error_on_mismatch :bool, default=False
             If True, raise an informative
             :class:`~iris.exceptions.MergeError` if registration fails.
 
diff --git a/lib/iris/analysis/_area_weighted.py b/lib/iris/analysis/_area_weighted.py
index bba7e01f4a..263f83838c 100644
--- a/lib/iris/analysis/_area_weighted.py
+++ b/lib/iris/analysis/_area_weighted.py
@@ -29,7 +29,7 @@ def __init__(self, src_grid_cube, target_grid_cube, mdtol=1):
             The :class:`~iris.cube.Cube` providing the source grid.
         target_grid_cube : :class:`~iris.cube.Cube`
             The :class:`~iris.cube.Cube` providing the target grid.
-        mdtol : float, optional
+        mdtol : float, default=1
             Tolerance of missing data. The value returned in each element of
             the returned array will be masked if the fraction of masked data
             exceeds mdtol. mdtol=0 means no missing data is tolerated while
diff --git a/lib/iris/analysis/_interpolation.py b/lib/iris/analysis/_interpolation.py
index 59863e3485..babc414ee4 100644
--- a/lib/iris/analysis/_interpolation.py
+++ b/lib/iris/analysis/_interpolation.py
@@ -123,7 +123,7 @@ def get_xy_coords(cube, dim_coords=False):
     ----------
     cube : :class:`iris.cube.Cube`
         An instance of :class:`iris.cube.Cube`.
-    dim_coords : bool, optional, default=False
+    dim_coords : bool, default=False
         Set this to True to only return dimension coordinates. Defaults to
         False.
 
@@ -482,7 +482,7 @@ def _points(self, sample_points, data, data_dims=None):
             The data to interpolate - not necessarily the data from the cube
             that was used to construct this interpolator. If the data has
             fewer dimensions, then data_dims must be defined.
-        data_dims : optional, default=None
+        data_dims : optional
             The dimensions of the given data array in terms of the original
             cube passed through to this interpolator's constructor. If None,
             the data dimensions must map one-to-one onto the increasing
@@ -574,7 +574,7 @@ def __call__(self, sample_points, collapse_scalar=True):
             A list of N iterables, where N is the number of coordinates
             passed to the constructor.
             [sample_values_for_coord_0, sample_values_for_coord_1, ...]
-        collapse_scalar : bool, optional
+        collapse_scalar : bool, default=True
             Whether to collapse the dimension of the scalar sample points
             in the resulting cube. Default is True.
 
diff --git a/lib/iris/analysis/_regrid.py b/lib/iris/analysis/_regrid.py
index 321194d1fc..be3f08278e 100644
--- a/lib/iris/analysis/_regrid.py
+++ b/lib/iris/analysis/_regrid.py
@@ -384,7 +384,7 @@ def __init__(self, src_grid_cube, target_grid_cube, weights=None):
             The :class:`~iris.cube.Cube` providing the source grid.
         tgt_grid_cube : :class:`~iris.cube.Cube`
             The :class:`~iris.cube.Cube` providing the target grid.
-        weights : optional, default=None
+        weights : optional
             A :class:`numpy.ndarray` instance that defines the weights
             for the grid cells of the source grid. Must have the same shape
             as the data of the source grid.
@@ -636,9 +636,9 @@ def _regrid(
             A 2-dimensional array of sample X values.
         sample_grid_y :
             A 2-dimensional array of sample Y values.
-        method: str, optional
+        method: str, default="linear"
             Either 'linear' or 'nearest'. The default method is 'linear'.
-        extrapolation_mode : str, optional
+        extrapolation_mode : str, default="nanmask"
             Must be one of the following strings:
 
             * 'linear' - The extrapolation points will be calculated by
@@ -656,7 +656,7 @@ def _regrid(
 
         Returns
         -------
-        NumPu array
+        NumPy array
             The regridded data as an N-dimensional NumPy array. The lengths
             of the X and Y dimensions will now match those of the sample
             grid.
diff --git a/lib/iris/analysis/cartography.py b/lib/iris/analysis/cartography.py
index 58c10c1926..d57f8ce8a3 100644
--- a/lib/iris/analysis/cartography.py
+++ b/lib/iris/analysis/cartography.py
@@ -205,7 +205,7 @@ def _xy_range(cube, mode=None):
     ----------
     cube :
         The cube for which to calculate xy extents.
-    mode : optional, default=None
+    mode : optional
         If the coordinate has bounds, set this to specify the
         min/max calculation.
         Set to iris.coords.POINT_MODE or iris.coords.BOUND_MODE.
@@ -397,7 +397,7 @@ def area_weights(cube, normalize=False):
     ----------
     cube : :class:`iris.cube.Cube`
         The cube to calculate area weights for.
-    normalize : bool, optional, default=False
+    normalize : bool, default=False
         If False, weights are grid cell areas. If True, weights are grid
         cell areas divided by the total grid area.
 
@@ -605,10 +605,10 @@ def project(cube, target_proj, nx=None, ny=None):
         An instance of the Cartopy Projection class, or an instance of
         :class:`iris.coord_systems.CoordSystem` from which a projection
         will be obtained.
-    nx : optional, default=None
+    nx : optional
         Desired number of sample points in the x direction for a domain
         covering the globe.
-    ny : optional, default=None
+    ny : optional
         Desired number of sample points in the y direction for a domain
         covering the globe.
 
diff --git a/lib/iris/analysis/geometry.py b/lib/iris/analysis/geometry.py
index a76498bf45..271858716c 100644
--- a/lib/iris/analysis/geometry.py
+++ b/lib/iris/analysis/geometry.py
@@ -163,17 +163,14 @@ def geometry_area_weights(cube, geometry, normalize=False):
         This function does not maintain laziness when called; it realises data.
         See more at :doc:`/userguide/real_and_lazy_data`.
 
-    Args:
-
-    * cube (:class:`iris.cube.Cube`):
+    Parameters
+    ----------
+    cube : :class:`iris.cube.Cube`
         A Cube containing a bounded, horizontal grid definition.
-    * geometry (a shapely geometry instance):
+    geometry : shapely geometry instance
         The geometry of interest. To produce meaningful results this geometry
         must have a non-zero area. Typically a Polygon or MultiPolygon.
-
-    Kwargs:
-
-    * normalize:
+    normalize : bool, default=False
         Calculate each individual cell weight as the cell area overlap between
         the cell and the given shapely geometry divided by the total cell area.
         Default is False.
diff --git a/lib/iris/analysis/maths.py b/lib/iris/analysis/maths.py
index 216d7e3892..3dbe98f49d 100644
--- a/lib/iris/analysis/maths.py
+++ b/lib/iris/analysis/maths.py
@@ -43,13 +43,15 @@ def _output_dtype(op, first_dtype, second_dtype=None, in_place=False):
         The dtype of the first or only argument to the operator.
     second_dtype : optional, default=None
         The dtype of the second argument to the operator.
-    in_place : bool, optional, default=False
+    in_place : bool, default=False
         Whether the operation is to be performed in place.
 
     Returns
     -------
     :class:`numpy.dtype`
 
+    Notes
+    -----
     .. note::
 
         The function always returns the dtype which would result if the
@@ -94,7 +96,7 @@ def abs(cube, in_place=False):
     ----------
     cube :
         An instance of :class:`iris.cube.Cube`.
-    in_place : bool, optional, default=False
+    in_place : bool, default=False
         Whether to create a new Cube, or alter the given "cube".
 
     Returns
@@ -152,8 +154,6 @@ def intersection_of_cubes(cube, other_cube):
           intersections = cubes.extract_overlapping(coords)
           cube1, cube2 = (intersections[0], intersections[1])
 
-    Notes
-    -----
     This function maintains laziness when called; it does not realise data.
     See more at :doc:`/userguide/real_and_lazy_data`.
 
@@ -221,15 +221,12 @@ def add(cube, other, dim=None, in_place=False):
     ----------
     cube : iris.cube.Cube
         First operand to add.
-
     other: iris.cube.Cube, iris.coords.Coord, number, numpy.ndarray or dask.array.Array
         Second operand to add.
-
     dim : int, optional
         If `other` is a coord which does not exist on the cube, specify the
         dimension to which it should be mapped.
-
-    in_place : bool, optional, default=False
+    in_place : bool, default=False
         If `True`, alters the input cube.  Otherwise a new cube is created.
 
     Returns
@@ -276,15 +273,12 @@ def subtract(cube, other, dim=None, in_place=False):
     ----------
     cube : iris.cube.Cube
         Cube from which to subtract.
-
     other: iris.cube.Cube, iris.coords.Coord, number, numpy.ndarray or dask.array.Array
         Object to subtract from the cube.
-
     dim : int, optional
         If `other` is a coord which does not exist on the cube, specify the
         dimension to which it should be mapped.
-
-    in_place : bool, optional, default=False
+    in_place : bool, default=False
         If `True`, alters the input cube.  Otherwise a new cube is created.
 
     Returns
@@ -342,7 +336,7 @@ def _add_subtract_common(
     dim : optional, default=None
         Dimension along which to apply `other` if it's a coordinate that is not
         found in `cube`
-    in_place : bool, optional, default=False
+    in_place : bool, default=False
         Whether or not to apply the operation in place to `cube` and `cube.data`
 
     """
@@ -386,15 +380,12 @@ def multiply(cube, other, dim=None, in_place=False):
     ----------
     cube : iris.cube.Cube
         First operand to multiply.
-
     other: iris.cube.Cube, iris.coords.Coord, number, numpy.ndarray or dask.array.Array
         Second operand to multiply.
-
     dim : int, optional
         If `other` is a coord which does not exist on the cube, specify the
         dimension to which it should be mapped.
-
-    in_place : bool, optional, default=False
+    in_place : bool, default=False
         If `True`, alters the input cube.  Otherwise a new cube is created.
 
     Returns
@@ -474,15 +465,12 @@ def divide(cube, other, dim=None, in_place=False):
     ----------
     cube : iris.cube.Cube
         Numerator.
-
     other: iris.cube.Cube, iris.coords.Coord, number, numpy.ndarray or dask.array.Array
         Denominator.
-
     dim : int, optional
         If `other` is a coord which does not exist on the cube, specify the
         dimension to which it should be mapped.
-
-    in_place : bool, optional, default=False
+    in_place : bool, default=False
         If `True`, alters the input cube.  Otherwise a new cube is created.
 
     Returns
@@ -546,7 +534,7 @@ def exponentiate(cube, exponent, in_place=False):
             powers of the basic units.
 
             e.g. Unit('meter^-2 kilogram second^-1')
-    in_place : bool, optional, default=False
+    in_place : bool, default=False
         Whether to create a new Cube, or alter the given "cube".
 
     Returns
@@ -557,6 +545,7 @@ def exponentiate(cube, exponent, in_place=False):
     -----
     This function maintains laziness when called; it does not realise data.
     See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     _assert_is_cube(cube)
     new_dtype = _output_dtype(
@@ -591,7 +580,7 @@ def exp(cube, in_place=False):
     ----------
     cube :
         An instance of :class:`iris.cube.Cube`.
-    in_place : bool, optional, default=False
+    in_place : bool, default=False
         Whether to create a new Cube, or alter the given "cube".
 
     Returns
@@ -621,7 +610,7 @@ def log(cube, in_place=False):
     ----------
     cube :
         An instance of :class:`iris.cube.Cube`.
-    in_place : bool, optional, default=False
+    in_place : bool, default=False
         Whether to create a new Cube, or alter the given "cube".
 
     Returns
@@ -653,7 +642,7 @@ def log2(cube, in_place=False):
     ----------
     cube :
         An instance of :class:`iris.cube.Cube`.
-    in_place : bool, optional, default=False
+    in_place : bool, default=False
         Whether to create a new Cube, or alter the given "cube".
 
     Returns
@@ -681,7 +670,7 @@ def log10(cube, in_place=False):
     ----------
     cube :
         An instance of :class:`iris.cube.Cube`.
-    in_place : bool, optional, default=False
+    in_place : bool, default=False
         Whether to create a new Cube, or alter the given "cube".
 
     Returns
@@ -722,17 +711,14 @@ def apply_ufunc(ufunc, cube, other=None, new_unit=None, new_name=None, in_place=
         :func:`numpy.mod`.
     cube :
         An instance of :class:`iris.cube.Cube`.
-
-    Kwargs:
-
-    other ::class:`iris.cube.Cube`, optional, default=False
+    other ::class:`iris.cube.Cube`, optional
         An instance of :class:`iris.cube.Cube` to be given as the second
         argument to :func:`numpy.ufunc`.
-    new_unit : optional, default=False
+    new_unit : optional
         Unit for the resulting Cube.
-    new_name : optional, default=False
+    new_name : optional
         Name for the resulting Cube.
-    in_place : bool, optional, default=False
+    in_place : bool, default=False
         Whether to create a new Cube, or alter the given "cube".
 
     Returns
@@ -836,14 +822,14 @@ def _binary_op_common(
         as the second argument
     new_dtype :
         The expected dtype of the output. Used in the case of scalar masked arrays
-    new_unit : optional, default=None
+    new_unit : optional
         Unit for the resulting quantity
-    dim : optional, default=None
+    dim : optional
         Dimension along which to apply `other` if it's a coordinate that is
         not found in `cube`
-    in_place : bool, optional, default=False
+    in_place : bool, default=False
         whether or not to apply the operation in place to `cube` and `cube.data`
-    sanitise_metadata : bool, optional, default=True
+    sanitise_metadata : bool, default=True
         Whether or not to remove metadata using _sanitise_metadata function
 
     """
@@ -1179,17 +1165,17 @@ def __call__(
         cube :
             An instance of :class:`iris.cube.Cube`, whose data is used
             as the first argument to the data function.
-        * other : optional, default=None
+        other : optional
             A cube, coord, ndarray, dask array or number whose data is used as the
             second argument to the data function.
-        * new_name : optional, default=None
+        new_name : optional
             Name for the resulting Cube.
-        * in_place : bool, optional, default=False
+        in_place : bool, default=False
             Whether to create a new Cube, or alter the given "cube".
-        * dim : optional, default=None
+        dim : optional
             Dimension along which to apply `other` if it's a coordinate that is
             not found in `cube`
-        ** kwargs_data_func :
+        **kwargs_data_func :
             Keyword arguments that get passed on to the data_func.
 
         Returns
diff --git a/lib/iris/analysis/stats.py b/lib/iris/analysis/stats.py
index f014dd5013..8df93571f1 100644
--- a/lib/iris/analysis/stats.py
+++ b/lib/iris/analysis/stats.py
@@ -31,7 +31,7 @@ def pearsonr(
         should either be the same shape and have the same dimension coordinates
         or one cube should be broadcastable to the other.  Broadcasting rules
         are the same as those for cube arithmetic (see :ref:`cube maths`).
-    corr_coords : str or list of str
+    corr_coords : str or list of str, optional
         The cube coordinate name(s) over which to calculate correlations. If no
         names are provided then correlation will be calculated over all common
         cube dimensions.
diff --git a/lib/iris/analysis/trajectory.py b/lib/iris/analysis/trajectory.py
index 9adb409970..1dd19cd724 100644
--- a/lib/iris/analysis/trajectory.py
+++ b/lib/iris/analysis/trajectory.py
@@ -43,7 +43,7 @@ def __init__(self, waypoints, sample_count=10):
         ----------
         waypoints :
             A sequence of dictionaries, mapping coordinate names to values.
-        sample_count : int, optional, default=10
+        sample_count : int, default=10
             The number of sample positions to use along the trajectory.
 
         Examples
@@ -156,7 +156,7 @@ def interpolate(self, cube, method=None):
         ----------
         cube :
              The source Cube to interpolate.
-        method :
+        method : optional
             The interpolation method to use; "linear" (default) or "nearest".
             Only nearest is available when specifying multi-dimensional
             coordinates.
@@ -191,7 +191,7 @@ def interpolate(cube, sample_points, method=None):
         The source Cube.
     sample_points :
         A sequence of coordinate (name) - values pairs.
-    method : optional, default=None
+    method : optional
         Request "linear" interpolation (default) or "nearest" neighbour.
         Only nearest neighbour is available when specifying multi-dimensional
         coordinates.
diff --git a/lib/iris/config.py b/lib/iris/config.py
index c31f856d54..6e350a456d 100644
--- a/lib/iris/config.py
+++ b/lib/iris/config.py
@@ -46,24 +46,24 @@ def get_logger(name, datefmt=None, fmt=None, level=None, propagate=None, handler
 
     Parameters
     ----------
-    name
+    name :
         The name of the logger. Typically this is the module filename that
         owns the logger.
-    datefmt: optional
+    datefmt : optional
         The date format string of the :class:`logging.Formatter`.
         Defaults to ``%d-%m-%Y %H:%M:%S``.
-    fmt: optional
+    fmt : optional
         The additional format string of the :class:`logging.Formatter`.
         This is appended to the default format string
         ``%(asctime)s %(name)s %(levelname)s - %(message)s``.
-    level: optional
+    level : optional
         The threshold level of the logger. Defaults to ``INFO``.
-    propagate: optional
+    propagate : optional
         Sets the ``propagate`` attribute of the :class:`logging.Logger`,
         which determines whether events logged to this logger will be
         passed to the handlers of higher level loggers. Defaults to
         ``False``.
-    handler: optional
+    handler : bool, default=True
         Create and attach a :class:`logging.StreamHandler` to the
         logger. Defaults to ``True``.
 
diff --git a/lib/iris/util.py b/lib/iris/util.py
index 4c896dc6dd..8c081e3ec0 100644
--- a/lib/iris/util.py
+++ b/lib/iris/util.py
@@ -103,7 +103,7 @@ def delta(ndarray, dimension, circular=False):
         The array over which to do the difference.
     dimension :
         The dimension over which to do the difference on ndarray.
-    circular : bool, optional, default=False
+    circular : bool, default=False
         If not False then return n results in the requested dimension
         with the delta between the last and first element included in
         the result otherwise the result will be of length n-1 (where n
@@ -171,7 +171,7 @@ def describe_diff(cube_a, cube_b, output_file=None):
     cube_b :
         An instance of :class:`iris.cube.Cube` or
         :class:`iris.cube.CubeMetadata`.
-    output_file :
+    output_file : optional
         A :class:`file` or file-like object to receive output. Defaults to
         sys.stdout.
 
@@ -287,11 +287,11 @@ def rolling_window(a, window=1, step=1, axis=-1):
     ----------
     a : array_like
         Array to add rolling window to
-    window : int, optional
+    window : int, default=1
         Size of rolling window
-    step : int, optional
+    step : int, default=1
         Size of step between rolling windows
-    axis : int, optional
+    axis : int, default=-1
         Axis to take the rolling window over
 
     Returns
@@ -359,7 +359,7 @@ def array_equal(array1, array2, withnans=False):
     ----------
     array1, array2 : arraylike
         args to be compared, normalised if necessary with :func:`np.asarray`.
-    withnans : bool, optional, default=False
+    withnans : bool, default=False
         When unset (default), the result is False if either input contains NaN
         points.  This is the normal floating-point arithmetic result.
         When set, return True if inputs contain the same value in all elements,
@@ -440,7 +440,7 @@ def between(lh, rh, lh_inclusive=True, rh_inclusive=True):
         The left hand element of the inequality
     rh :
         The right hand element of the inequality
-    lh_inclusive : bool, optional
+    lh_inclusive : bool, default=True
         Affects the left hand comparison operator to use in the inequality.
         True for ``<=`` false for ``<``. Defaults to True.
     rh_inclusive : bool, default=True
@@ -579,9 +579,9 @@ def monotonic(array, strict=False, return_direction=False):
 
     Parameters
     ----------
-    strict : boolean, optional, default=False
+    strict : boolean, default=False
         Flag to enable strict monotonic checking
-    return_direction : bool, optional, default=False
+    return_direction : bool, default=False
         Flag to change return behaviour to return
         (monotonic_status, direction). Direction will be 1 for positive
         or -1 for negative. The direction is meaningless if the array is
@@ -1022,10 +1022,10 @@ def clip_string(the_str, clip_length=70, rider="..."):
     ----------
     the_str : str
         The string to be clipped
-    clip_length :
+    clip_length : int, default=70
         The length in characters that the input string should be clipped
         to. Defaults to a preconfigured value if not specified.
-    rider : str, optional, default="..."
+    rider : str, default="..."
         A series of characters appended at the end of the returned
         string to show it has been clipped. Defaults to a preconfigured
         value if not specified.
@@ -1100,7 +1100,7 @@ def new_axis(src_cube, scalar_coord=None, expand_extras=()):  # maybe not lazy
     ----------
     src_cube : :class:`iris.cube.Cube`
         Source cube on which to generate a new axis.
-    scalar_coord : :class:`iris.coord.Coord` or 'string', optional, default=None
+    scalar_coord : :class:`iris.coord.Coord` or 'string', optional
         Scalar coordinate to promote to a dimension coordinate.
     expand_extras : iterable, optional
         Auxiliary coordinates, ancillary variables and cell measures which will
@@ -1367,10 +1367,8 @@ def regular_points(zeroth, step, count):
     ----------
     zeroth : number
         The value *prior* to the first point value.
-
     step : number
         The numeric difference between successive point values.
-
     count : number
         The number of point values.
 
@@ -1760,10 +1758,10 @@ def find_discontiguities(cube, rel_tol=1e-5, abs_tol=1e-8):
     cube : `iris.cube.Cube`
         The cube to be checked for discontinuities in its 'x' and 'y'
         coordinates. These coordinates must be 2D.
-    rel_tol : float, optional, default=1e-5
+    rel_tol : float, default=1e-5
         The relative equality tolerance to apply in coordinate bounds
         checking.
-    abs_tol : float, optional, default=1e-8
+    abs_tol : float, default=1e-8
         The absolute value tolerance to apply in coordinate bounds
         checking.
 
@@ -1908,15 +1906,12 @@ def mask_cube(cube, points_to_mask, in_place=False, dim=None):
     ----------
     cube : iris.cube.Cube
         Cube containing data that requires masking.
-
     points_to_mask : numpy.ndarray, dask.array.Array, iris.coords.Coord or iris.cube.Cube
         Specifies booleans (or ones and zeros) indicating which points will
         be masked.
-
     in_place : bool, default=False
         If `True`, masking is applied to the input cube.  Otherwise a copy is
         masked and returned.
-
     dim : int, optional
         If `points_to_mask` is a coord which does not exist on the cube,
         specify the dimension to which it should be mapped.