DOC: update the DataFrame.update() docstring (#20201)

Author: kantologist

pandas/core/frame.py

@@ -4534,21 +4534,44 @@ def combiner(x, y, needs_i8_conversion=False):
     def update(self, other, join='left', overwrite=True, filter_func=None,
                raise_conflict=False):
         """
-        Modify DataFrame in place using non-NA values from passed
-        DataFrame. Aligns on indices
+        Modify in place using non-NA values from another DataFrame.
+
+        Aligns on indices. There is no return value.
 
         Parameters
         ----------
         other : DataFrame, or object coercible into a DataFrame
+            Should have at least one matching index/column label
+            with the original DataFrame. If a Series is passed,
+            its name attribute must be set, and that will be
+            used as the column name to align with the original DataFrame.
         join : {'left'}, default 'left'
-        overwrite : boolean, default True
-            If True then overwrite values for common keys in the calling frame
-        filter_func : callable(1d-array) -> 1d-array<boolean>, default None
+            Only left join is implemented, keeping the index and columns of the
+            original object.
+        overwrite : bool, default True
+            How to handle non-NA values for overlapping keys:
+
+            * True: overwrite original DataFrame's values
+              with values from `other`.
+            * False: only update values that are NA in
+              the original DataFrame.
+
+        filter_func : callable(1d-array) -> boolean 1d-array, optional
             Can choose to replace values other than NA. Return True for values
-            that should be updated
-        raise_conflict : boolean
-            If True, will raise an error if the DataFrame and other both
-            contain data in the same place.
+            that should be updated.
+        raise_conflict : bool, default False
+            If True, will raise a ValueError if the DataFrame and `other`
+            both contain non-NA data in the same place.
+
+        Raises
+        ------
+        ValueError
+            When `raise_conflict` is True and there's overlapping non-NA data.
+
+        See Also
+        --------
+        dict.update : Similar method for dictionaries.
+        DataFrame.merge : For column(s)-on-columns(s) operations.
 
         Examples
         --------
@@ -4563,6 +4586,9 @@ def update(self, other, join='left', overwrite=True, filter_func=None,
         1  2  5
         2  3  6
 
+        The DataFrame's length does not increase as a result of the update,
+        only values at matching index/column labels are updated.
+
         >>> df = pd.DataFrame({'A': ['a', 'b', 'c'],
         ...                    'B': ['x', 'y', 'z']})
         >>> new_df = pd.DataFrame({'B': ['d', 'e', 'f', 'g', 'h', 'i']})
@@ -4573,6 +4599,8 @@ def update(self, other, join='left', overwrite=True, filter_func=None,
         1  b  e
         2  c  f
 
+        For Series, it's name attribute must be set.
+
         >>> df = pd.DataFrame({'A': ['a', 'b', 'c'],
         ...                    'B': ['x', 'y', 'z']})
         >>> new_column = pd.Series(['d', 'e'], name='B', index=[0, 2])
@@ -4592,7 +4620,7 @@ def update(self, other, join='left', overwrite=True, filter_func=None,
         1  b  d
         2  c  e
 
-        If ``other`` contains NaNs the corresponding values are not updated
+        If `other` contains NaNs the corresponding values are not updated
         in the original dataframe.
 
         >>> df = pd.DataFrame({'A': [1, 2, 3],