Apply suggestions from code review

Co-authored-by: Deepak Cherian <[email protected]>

doc/whats-new.rst

@@ -27,7 +27,7 @@ New Features
 - Add ``unit`` - keyword argument to :py:func:`date_range` and ``microsecond`` parsing to
   iso8601-parser (:pull:`9885`).
   By `Kai Mühlbauer <https://github.com/kmuehlbauer>`_.
-- Split out ``CFDatetimeCoder`` in ``xr.coders``, make ``decode_times`` keyword argument
+- Split out ``CFDatetimeCoder`` as public API in ``xr.coders``, make ``decode_times`` keyword argument
   consume ``CFDatetimeCoder``.
 
 
@@ -46,8 +46,7 @@ Deprecations
   :py:func:`date_range` (:pull:`9882`).
   By `Kai Mühlbauer <https://github.com/kmuehlbauer>`_.
 - Time decoding related kwarg ``use_cftime`` is deprecated. Use keyword argument
-  ``decode_times=CFDatetimeCoder(use_cftime=True)`` in the respective functions
-  instead.
+  ``decode_times=CFDatetimeCoder(use_cftime=True)`` in :py:func:`~xarray.open_dataset`, :py:func:`~xarray.open_dataarray`, :py:func:`~xarray.open_datatree`, :py:func:`~xarray.open_groups`, :py:func:`~xarray.open_zarr` and :py:func:`~xarray.decode_cf` instead.
   By `Kai Mühlbauer <https://github.com/kmuehlbauer>`_.
 
 Bug fixes

xarray/backends/api.py

@@ -549,7 +549,7 @@ def open_dataset(
         This keyword may not be supported by all the backends.
     decode_times : bool, CFDatetimeCoder or dict-like, optional
         If True, decode times encoded in the standard NetCDF datetime format
-        into datetime objects. Otherwise, use CFDatetimeCoder or leave them encoded as numbers.
+        into datetime objects. Otherwise, use ``CFDatetimeCoder`` or leave them encoded as numbers.
         Pass a mapping, e.g. ``{"my_variable": False}``,
         to toggle this feature per-variable individually.
         This keyword may not be supported by all the backends.
@@ -573,8 +573,8 @@ def open_dataset(
         raise an error. Pass a mapping, e.g. ``{"my_variable": False}``,
         to toggle this feature per-variable individually.
         This keyword may not be supported by all the backends.
-        Usage of 'use_cftime' as kwarg is deprecated. Please initialize it
-        with CFDatetimeCoder and 'decode_times' kwarg.
+        .. deprecated:: 2024.12.0
+           Please initialize it with ``CFDatetimeCoder`` and ``decode_times`` kwarg.
     concat_characters : bool or dict-like, optional
         If True, concatenate along the last dimension of character arrays to
         form string arrays. Dimensions will only be concatenated over (and

xarray/conventions.py

@@ -199,7 +199,7 @@ def decode_cf_variable(
             if use_cftime is not None:
                 from warnings import warn
 
-                warn(
+                emit_user_level_warning(
                     "Usage of 'use_cftime' as kwarg is deprecated. "
                     "Please initialize it with CFDatetimeCoder and "
                     "'decode_times' kwarg.",