Update docstring for compute and persist (#8903)

* Update docstring for compute and persist

* Add compute reference to load docstring for dask array

* Use new wording for persist

Co-authored-by: Justus Magin <keewis@users.noreply.github.com>

* Update xarray/core/dataarray.py

Co-authored-by: Justus Magin <keewis@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Justus Magin <keewis@users.noreply.github.com>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Add "all" to persist docstring

* Apply suggestions from code review

Co-authored-by: Maximilian Roos <5635139+max-sixty@users.noreply.github.com>

---------

Co-authored-by: Justus Magin <keewis@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Maximilian Roos <5635139+max-sixty@users.noreply.github.com>

Author: 4 people

xarray/core/dataarray.py

@@ -1126,6 +1126,8 @@ def load(self, **kwargs) -> Self:
         """Manually trigger loading of this array's data from disk or a
         remote source into memory and return this array.
 
+        Unlike compute, the original dataset is modified and returned.
+
         Normally, it should not be necessary to call this method in user code,
         because all xarray functions should either work on deferred data or
         load data automatically. However, this method can be necessary when
@@ -1148,8 +1150,9 @@ def load(self, **kwargs) -> Self:
 
     def compute(self, **kwargs) -> Self:
         """Manually trigger loading of this array's data from disk or a
-        remote source into memory and return a new array. The original is
-        left unaltered.
+        remote source into memory and return a new array.
+
+        Unlike load, the original is left unaltered.
 
         Normally, it should not be necessary to call this method in user code,
         because all xarray functions should either work on deferred data or
@@ -1161,6 +1164,11 @@ def compute(self, **kwargs) -> Self:
         **kwargs : dict
             Additional keyword arguments passed on to ``dask.compute``.
 
+        Returns
+        -------
+        object : DataArray
+            New object with the data and all coordinates as in-memory arrays.
+
         See Also
         --------
         dask.compute
@@ -1174,12 +1182,18 @@ def persist(self, **kwargs) -> Self:
         This keeps them as dask arrays but encourages them to keep data in
         memory.  This is particularly useful when on a distributed machine.
         When on a single machine consider using ``.compute()`` instead.
+        Like compute (but unlike load), the original dataset is left unaltered.
 
         Parameters
         ----------
         **kwargs : dict
             Additional keyword arguments passed on to ``dask.persist``.
 
+        Returns
+        -------
+        object : DataArray
+            New object with all dask-backed data and coordinates as persisted dask arrays.
+
         See Also
         --------
         dask.persist

xarray/core/dataset.py

@@ -1005,6 +1005,11 @@ def compute(self, **kwargs) -> Self:
         **kwargs : dict
             Additional keyword arguments passed on to ``dask.compute``.
 
+        Returns
+        -------
+        object : Dataset
+            New object with lazy data variables and coordinates as in-memory arrays.
+
         See Also
         --------
         dask.compute
@@ -1037,12 +1042,18 @@ def persist(self, **kwargs) -> Self:
         operation keeps the data as dask arrays. This is particularly useful
         when using the dask.distributed scheduler and you want to load a large
         amount of data into distributed memory.
+        Like compute (but unlike load), the original dataset is left unaltered.
 
         Parameters
         ----------
         **kwargs : dict
             Additional keyword arguments passed on to ``dask.persist``.
 
+        Returns
+        -------
+        object : Dataset
+            New object with all dask-backed coordinates and data variables as persisted dask arrays.
+
         See Also
         --------
         dask.persist