DOC: Adding examples to update docstring (#16812)

pandas/core/frame.py

@@ -4154,6 +4154,43 @@ def update(self, other, join='left', overwrite=True, filter_func=None,
         raise_conflict : boolean
             If True, will raise an error if the DataFrame and other both
             contain data in the same place.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'A': ['a', 'b', 'c'],
+                               'B': [1, 2, 3]})
+        >>> new_df = pd.DataFrame({'B': ['d', 'e', 'f'],
+                                   'C': ['g', 'h', 'i']})
+        >>> df.update(new_df)
+        >>> df
+           A  B
+        0  a  d
+        1  b  e
+        2  c  f
+
+        >>> df = pd.DataFrame({'A': ['a', 'b', 'c'],
+                               'B': [1, 2, 3]})
+        >>> new_column = pd.Series(['d', 'e', 'f'], name='B')
+        >>> df.update(new_column)
+        >>> df
+           A  B
+        0  a  d
+        1  b  e
+        2  c  f
+
+        If ``other`` contains NaNs the corresponding values are not updated
+        in the original dataframe.
+
+        >>> df = pd.DataFrame({'A': ['a', 'b', 'c'],
+                               'B': [1, 2, 3]})
+        >>> new_df = pd.DataFrame({'B': ['d', np.nan, 'f']})
+        >>> df.update(new_df)
+        >>> df
+           A  B
+        0  a  d
+        1  b  2
+        2  c  f
+
         """
         import pandas.core.computation.expressions as expressions
         # TODO: Support other joins

pandas/core/series.py

@@ -1780,6 +1780,38 @@ def update(self, other):
         Parameters
         ----------
         other : Series
+
+        Examples
+        --------
+        >>> s = pd.Series(['a', 'b', 'c', 'd'])
+        >>> s.update(pd.Series([1, 2, 3, 4]))
+        >>> s
+        0    1
+        1    2
+        2    3
+        3    4
+        dtype: object
+
+        >>> s = pd.Series(['a', 'b', 'c', 'd'])
+        >>> s.update(pd.Series([1, 4], index=[0, 3]))
+        >>> s
+        0    1
+        1    b
+        2    c
+        3    4
+        dtype: object
+
+        If ``other`` contains NaNs the corresponding values are not updated
+        in the original Series.
+
+        >>> s = pd.Series(['a', 'b', 'c', 'd'])
+        >>> s.update(pd.Series([1, 2, np.nan, 4]))
+        >>> s
+        0    1
+        1    2
+        2    c
+        3    4
+        dtype: object
         """
         other = other.reindex_like(self)
         mask = notna(other)