From 351b0aac671a910803dcf618a18bb33cc8f8f2ab Mon Sep 17 00:00:00 2001
From: keewis <keewis@users.noreply.github.com>
Date: Wed, 24 Feb 2021 22:17:25 +0100
Subject: [PATCH] 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]
---
 doc/whats-new.rst      |  5 +++++
 xarray/core/dataset.py | 11 ++++++++++-
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/doc/whats-new.rst b/doc/whats-new.rst
index 5051a64af79..a181c2b3320 100644
--- a/doc/whats-new.rst
+++ b/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
 ~~~~~~~~~~~~~~~~
diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py
index bdf29eda197..9faf74dd4bc 100644
--- a/xarray/core/dataset.py
+++ b/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())