diff --git a/doc/whats-new.rst b/doc/whats-new.rst
index f619284437b..4300f1b188a 100644
--- a/doc/whats-new.rst
+++ b/doc/whats-new.rst
@@ -47,7 +47,9 @@ Deprecations
 
 - ``dim`` argument to :py:meth:`DataArray.integrate` is being deprecated in
   favour of a ``coord`` argument, for consistency with :py:meth:`Dataset.integrate`.
-  For now using ``dim`` issues a ``FutureWarning``. By `Tom Nicholas <https://github.com/TomNicholas>`_.
+  For now using ``dim`` issues a ``FutureWarning``. It will be removed in
+  version 0.19.0 (:pull:`3993`).
+  By `Tom Nicholas <https://github.com/TomNicholas>`_.
 
 
 New Features
diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py
index fc53dbee26e..7ca5ff50eba 100644
--- a/xarray/core/dataarray.py
+++ b/xarray/core/dataarray.py
@@ -1707,7 +1707,7 @@ def swap_dims(
         dims_dict : dict-like
             Dictionary whose keys are current dimension names and whose values
             are new names.
-        **dim_kwargs : {dim: , ...}, optional
+        **dims_kwargs : {existing_dim: new_dim, ...}, optional
             The keyword arguments form of ``dims_dict``.
             One of dims_dict or dims_kwargs must be provided.
 
@@ -3479,21 +3479,22 @@ def integrate(
 
         Parameters
         ----------
-        coord: hashable, or a sequence of hashable
+        coord : hashable, or sequence of hashable
             Coordinate(s) used for the integration.
         dim : hashable, or sequence of hashable
             Coordinate(s) used for the integration.
-        datetime_unit: {'Y', 'M', 'W', 'D', 'h', 'm', 's', 'ms', 'us', 'ns', \
+        datetime_unit : {'Y', 'M', 'W', 'D', 'h', 'm', 's', 'ms', 'us', 'ns', \
                         'ps', 'fs', 'as'}, optional
+            Specify the unit if a datetime coordinate is used.
 
         Returns
         -------
-        integrated: DataArray
+        integrated : DataArray
 
         See also
         --------
         Dataset.integrate
-        numpy.trapz: corresponding numpy function
+        numpy.trapz : corresponding numpy function
 
         Examples
         --------
diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py
index 6a609bfe7b7..7d51adb5244 100644
--- a/xarray/core/dataset.py
+++ b/xarray/core/dataset.py
@@ -3160,7 +3160,7 @@ def swap_dims(
         dims_dict : dict-like
             Dictionary whose keys are current dimension names and whose values
             are new names.
-        **dim_kwargs : {existing_dim: new_dim, ...}, optional
+        **dims_kwargs : {existing_dim: new_dim, ...}, optional
             The keyword arguments form of ``dims_dict``.
             One of dims_dict or dims_kwargs must be provided.
 
@@ -5956,9 +5956,9 @@ def integrate(
 
         Parameters
         ----------
-        coord: hashable, or a sequence of hashable
+        coord : hashable, or sequence of hashable
             Coordinate(s) used for the integration.
-        datetime_unit: {'Y', 'M', 'W', 'D', 'h', 'm', 's', 'ms', 'us', 'ns', \
+        datetime_unit : {'Y', 'M', 'W', 'D', 'h', 'm', 's', 'ms', 'us', 'ns', \
                         'ps', 'fs', 'as'}, optional
             Specify the unit if datetime coordinate is used.
 
@@ -5969,7 +5969,7 @@ def integrate(
         See also
         --------
         DataArray.integrate
-        numpy.trapz: corresponding numpy function
+        numpy.trapz : corresponding numpy function
 
         Examples
         --------