Further fixes and tweaks.

Author: pp-mo

docs/userdocs/user_guide/common_operations.rst

@@ -125,14 +125,17 @@ Equality Testing
 ----------------
 We implement equality operations ``==`` / ``!=`` for all the core data objects.
 
-However, simple equality testing on :class:`@ncdata.NcData` and :class:`@ncdata.NcVariable`
-objects can be very costly if it requires comparing large data arrays.
+.. warning::
+    The equality testing actually calls the :func:`ncdata.utils.dataset_differences` and
+    :func:`ncdata.utils.variable_differences` utility functions.
+
+    This can be very costly if it needs to compare large data arrays.
 
-If you need to avoid comparing large (and possibly lazy) arrays then you can use the
+If you need to avoid comparing large (and possibly lazy) arrays then you should use the
 :func:`ncdata.utils.dataset_differences` and
-:func:`ncdata.utils.variable_differences` utility functions.
-These functions also provide multiple options to enable more tolerant comparison,
-such as allowing variables to have a different ordering.
+:func:`ncdata.utils.variable_differences` utility functions directly.
+These enable you to use the provided tolerance options, such as ignoring differences in
+data content, or accepting that attributes are present in a different order.
 
 See: :ref:`utils_equality`
 

docs/userdocs/user_guide/howtos.rst

@@ -413,7 +413,7 @@ You can also slice data directly, which simply acts on the dimensions in order:
     >>> data_region_2 == data_region
     True
 
-See: :ref:`indexing_overview`
+See: :ref:`utils_indexing`
 
 
 Read data from a NetCDF file

docs/userdocs/user_guide/utilities.rst

@@ -20,8 +20,6 @@ The functions :func:`~ncdata.utils.dataset_differences` and
 :func:`~ncdata.utils.variable_differences` produce a list of messages detailing all the
 ways in which two datasets are different.
 
-See: :ref:`equality_checks`
-
 For Example:
 ^^^^^^^^^^^^
 .. testsetup::
@@ -58,13 +56,16 @@ For Example:
    :func:`~ncdata.utils.variable_differences` is also provided.
 
 .. note::
-    The ``==`` and ``!-`` operations on  :class:`ncdata.NcData` and
-    :class:`ncdata.NcVariable` are implemented to call these utility functions.
-    However, lacking a keyword interface to enable any tolerance options, the operations
-    compare absolutely everything, and so can be very performance intensive if large data
-    arrays are present.
+    The ``==`` and ``!=`` operations on  :class:`ncdata.NcData` and
+    :class:`ncdata.NcVariable` simply call these utility functions to see if there are
+    any differences.
+
+    .. warning::
+        As they lack a keyword interface, these operations have no tolerance options
+        and check absolutely everything.  This includes full data-array comparisons,
+        which could be very costly in time or space if data arrays are large.
 
-.. _indexing_overview:
+.. _utils_indexing:
 
 Sub-indexing
 ------------

lib/ncdata/utils/_compare_nc_datasets.py

@@ -38,7 +38,7 @@ def dataset_differences(
     :class:`~ncdata.NcData` objects.
     File paths are opened with the :mod:`netCDF4` module.
 
-    See: :ref:`equality_checks`
+    See: :ref:`equality_testing`
 
     Parameters
     ----------
@@ -328,7 +328,7 @@ def variable_differences(
     r"""
     Compare variables.
 
-    See: :ref:`equality_checks`
+    See: :ref:`equality_testing`
 
     Parameters
     ----------

lib/ncdata/utils/_copy.py

@@ -32,22 +32,23 @@ def ncdata_copy(ncdata: NcData) -> NcData:
     Notes
     -----
     This operation is now also available as an object method:
-    :meth:`~ncdata.NcData.copy`.  For example:
+    :meth:`~ncdata.NcData.copy`.
 
     Syntactically, this is generally more convenient, but the operation is identical.
+
     For example:
 
     .. testsetup::
 
         >>> from ncdata import NcData
-        >>> from ncdata.utils import dataset_differences, ncdata_copy
+        >>> from ncdata.utils import ncdata_copy
         >>> data = NcData()
 
     .. doctest::
 
         >>> data1 = ncdata_copy(data)
         >>> data2 = data.copy()
-        >>> dataset_differences(data1, data2) == []
+        >>> data1 == data2
         True
 
     """