Clarify drop_vars return value. (#4244)

* Clarify drop_vars return value.

The previous documentation was not clear about whether the variable
dropping was "inplace" or created a fresh Dataset.

* Update xarray/core/dataarray.py

Fix syntax error in docstring markdown.

Co-authored-by: Maximilian Roos <[email protected]>

* Update xarray/core/dataarray.py

Co-authored-by: Maximilian Roos <[email protected]>

Co-authored-by: Robert P. Goldman <[email protected]>
Co-authored-by: Maximilian Roos <[email protected]>
Co-authored-by: Deepak Cherian <[email protected]>
Co-authored-by: dcherian <[email protected]>

Author: 3 people

xarray/core/dataarray.py

@@ -2012,7 +2012,7 @@ def T(self) -> "DataArray":
     def drop_vars(
         self, names: Union[Hashable, Iterable[Hashable]], *, errors: str = "raise"
     ) -> "DataArray":
-        """Drop variables from this DataArray.
+        """Returns an array with dropped variables.
 
         Parameters
         ----------
@@ -2026,7 +2026,7 @@ def drop_vars(
         Returns
         -------
         dropped : Dataset
-
+            New Dataset copied from `self` with variables removed.
         """
         ds = self._to_temp_dataset().drop_vars(names, errors=errors)
         return self._from_temp_dataset(ds)