document update as inplace (#4932)

* explicitly state that update works inplace

* point to assign

* update whats-new.rst [skip-ci]

* rewrite the docstring [skip-ci]

* deprecate the return value of Dataset.update

* add the issue and pull request numbers [skip-ci]

* add a ETA for the removal of the return value [skip-ci]

Author: keewis

doc/whats-new.rst

@@ -79,6 +79,9 @@ Deprecations
   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>`_.
+- the return value of :py:meth:`Dataset.update` is being deprecated to make it work more
+  like :py:meth:`dict.update`. It will be removed in version 0.19.0 (:pull:`4932`).
+  By `Justus Magin <https://github.com/keewis>`_.
 
 
 New Features
@@ -181,6 +184,8 @@ Documentation
 - add concat examples and improve combining documentation (:issue:`4620`, :pull:`4645`).
   By `Ray Bell <https://github.com/raybellwaves>`_ and
   `Justus Magin <https://github.com/keewis>`_.
+- explicitly mention that :py:meth:`Dataset.update` updates inplace (:issue:`2951`, :pull:`4932`).
+  By `Justus Magin <https://github.com/keewis>`_.
 
 Internal Changes
 ~~~~~~~~~~~~~~~~

xarray/core/dataset.py

@@ -3865,6 +3865,8 @@ def unstack(
     def update(self, other: "CoercibleMapping") -> "Dataset":
         """Update this dataset's variables with those from another dataset.
 
+        Just like :py:meth:`dict.update` this is a in-place operation.
+
         Parameters
         ----------
         other : Dataset or mapping
@@ -3879,13 +3881,20 @@ def update(self, other: "CoercibleMapping") -> "Dataset":
         Returns
         -------
         updated : Dataset
-            Updated dataset.
+            Updated dataset. Note that since the update is in-place this is the input
+            dataset.
+
+            It is deprecated since version 0.17 and scheduled to be removed in 0.19.
 
         Raises
         ------
         ValueError
             If any dimensions would have inconsistent sizes in the updated
             dataset.
+
+        See Also
+        --------
+        Dataset.assign
         """
         merge_result = dataset_update_method(self, other)
         return self._replace(inplace=True, **merge_result._asdict())