From ebe32befc5242bc3f0eedc5ae37335c9f196b991 Mon Sep 17 00:00:00 2001
From: Paul Reidy <paul_reidy@outlook.com>
Date: Thu, 12 Oct 2017 23:17:50 +0100
Subject: [PATCH] DOC: Adding examples to update docstring (#16812)

---
 pandas/core/frame.py  | 36 ++++++++++++++++++++++++++++++++++++
 pandas/core/series.py | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+)

diff --git a/pandas/core/frame.py b/pandas/core/frame.py
index c7e8c0da75e2c..21849dbd59d7f 100644
--- a/pandas/core/frame.py
+++ b/pandas/core/frame.py
@@ -4154,6 +4154,42 @@ 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
diff --git a/pandas/core/series.py b/pandas/core/series.py
index 8499f8b55d2d0..e8668a38b6b2a 100644
--- a/pandas/core/series.py
+++ b/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)