adding some documentation

tests/fixtures.py

@@ -178,7 +178,7 @@
 
 
 def generate_dataset(
-    cf_compliant: bool, has_bounds: bool, unsupported=False
+    cf_compliant: bool, has_bounds: bool, unsupported: bool = False
 ) -> xr.Dataset:
     """Generates a dataset using coordinate and data variable fixtures.
 
@@ -189,12 +189,22 @@ def generate_dataset(
     has_bounds : bool, optional
         Include bounds for coordinates. This also adds the "bounds" attribute
         to existing coordinates to link them to their respective bounds.
+    unsupported : bool, optional
+        Create time units that are unsupported and cannot be decoded.
+        Note that cf_compliant must be set to False.
 
     Returns
     -------
     xr.Dataset
         Test dataset.
     """
+
+    if unsupported & cf_compliant:
+        raise ValueError(
+            "Cannot set cf_compliant=True and unsupported=True. \n"
+            "Set cf_compliant=False."
+        )
+
     if has_bounds:
         ds = xr.Dataset(
             data_vars={

xcdat/dataset.py

@@ -37,9 +37,10 @@ def open_dataset(
         The key of the non-bounds data variable to keep in the Dataset,
         alongside any existing bounds data variables, by default None.
     decode_times: bool, optional
-        If True, decode times encoded in the standard NetCDF datetime format
-        into datetime objects. Otherwise, leave them encoded as numbers.
-        This keyword may not be supported by all the backends, by default True.
+        If True, attempt to decode times encoded in the standard NetCDF
+        datetime format into datetime objects. Otherwise, leave them encoded
+        as numbers. This keyword may not be supported by all the backends,
+        by default True.
     center_times: bool, optional
         If True, center time coordinates using the midpoint between its upper
         and lower bounds. Otherwise, use the provided time coordinates, by
@@ -232,7 +233,8 @@ def decode_non_cf_time(dataset: xr.Dataset) -> xr.Dataset:
     ----------
     dataset : xr.Dataset
         Dataset with numerically encoded time coordinates and time bounds (if
-        they exist).
+        they exist). If the time coordinates cannot be decoded then the original
+        dataset is returned.
 
     Returns
     -------
@@ -619,6 +621,11 @@ def _split_time_units_attr(units_attr: str) -> Tuple[str, str]:
     Tuple[str, str]
         The units (e.g, "months") and the reference date (e.g., "1800-01-01").
         If the units attribute doesn't exist for the time coordinates.
+
+    Raises
+    ------
+    ValueError
+        If the time units attribute is not of the form `X since Y`.
     """
     if units_attr is None:
         raise KeyError("No 'units' attribute found for the dataset's time coordinates.")