update the docstring of diff (#3909)

* don't document the dim parameter as optional

* update whats-new.rst

* fix the reference syntax

Author: keewis

doc/whats-new.rst

@@ -46,6 +46,10 @@ Bug fixes
 
 Documentation
 ~~~~~~~~~~~~~
+- update the docstring of :py:meth:`Dataset.diff` and
+  :py:meth:`DataArray.diff` so it does document the ``dim``
+  parameter as required. (:issue:`1040`, :pull:`3909`)
+  By `Justus Magin <https://github.com/keewis>`_.
 
 
 Internal Changes

xarray/core/dataarray.py

@@ -2696,7 +2696,7 @@ def diff(self, dim: Hashable, n: int = 1, label: Hashable = "upper") -> "DataArr
 
         Parameters
         ----------
-        dim : hashable, optional
+        dim : hashable
             Dimension over which to calculate the finite difference.
         n : int, optional
             The number of times values are differenced.

xarray/core/dataset.py

@@ -4901,7 +4901,7 @@ def diff(self, dim, n=1, label="upper"):
 
         Parameters
         ----------
-        dim : str, optional
+        dim : str
             Dimension over which to calculate the finite difference.
         n : int, optional
             The number of times values are differenced.