diff --git a/examples/lines_bars_and_markers/masked_demo.py b/examples/lines_bars_and_markers/masked_demo.py
index 66756847f6f1..52ea1a68b772 100644
--- a/examples/lines_bars_and_markers/masked_demo.py
+++ b/examples/lines_bars_and_markers/masked_demo.py
@@ -1,30 +1,51 @@
-'''
-===========
-Masked Demo
-===========
+"""
+==============================
+Plotting masked and NaN values
+==============================
 
-Plot lines with points masked out.
+Sometimes you need to plot data with missing values.
 
-This would typically be used with gappy data, to
-break the line at the data gaps.
-'''
+One possibility is to simply remove undesired data points. The line plotted
+through the remaining data will be continuous, and not indicate where the
+missing data is located.
+
+If it is useful to have gaps in the line where the data is missing, then the
+undesired points can be indicated using a `masked array`_ or by setting their
+values to NaN. No marker will be drawn where either x or y are masked and, if
+plotting with a line, it will be broken there.
+
+.. _masked array:
+   https://docs.scipy.org/doc/numpy/reference/maskedarray.generic.html
+
+The following example illustrates the three cases:
+
+1) Removing points.
+2) Masking points.
+3) Setting to NaN.
+"""
 
 import matplotlib.pyplot as plt
 import numpy as np
 
-x = np.arange(0, 2*np.pi, 0.02)
-y = np.sin(x)
-y1 = np.sin(2*x)
-y2 = np.sin(3*x)
-ym1 = np.ma.masked_where(y1 > 0.5, y1)
-ym2 = np.ma.masked_where(y2 < -0.5, y2)
-
-lines = plt.plot(x, y, x, ym1, x, ym2, 'o')
-plt.setp(lines[0], linewidth=4)
-plt.setp(lines[1], linewidth=2)
-plt.setp(lines[2], markersize=10)
-
-plt.legend(('No mask', 'Masked if > 0.5', 'Masked if < -0.5'),
-           loc='upper right')
-plt.title('Masked line demo')
+
+x = np.linspace(-np.pi/2, np.pi/2, 31)
+y = np.cos(x)**3
+
+# 1) remove points where y > 0.7
+x2 = x[y <= 0.7]
+y2 = y[y <= 0.7]
+
+# 2) mask points where y > 0.7
+y3 = np.ma.masked_where(y > 0.7, y)
+
+# 3) set to NaN where y > 0.7
+y4 = y.copy()
+y4[y3 > 0.7] = np.nan
+
+plt.plot(x*0.1, y, 'o-', color='lightgrey', label='No mask')
+plt.plot(x2*0.4, y2, 'o-', label='Points removed')
+plt.plot(x*0.7, y3, 'o-', label='Masked values')
+plt.plot(x*1.0, y4, 'o-', label='NaN values')
+plt.legend()
+plt.title('Masked and NaN data')
 plt.show()
diff --git a/examples/lines_bars_and_markers/nan_test.py b/examples/lines_bars_and_markers/nan_test.py
deleted file mode 100644
index 4216f6960ae0..000000000000
--- a/examples/lines_bars_and_markers/nan_test.py
+++ /dev/null
@@ -1,34 +0,0 @@
-"""
-========
-Nan Test
-========
-
-Example: simple line plots with NaNs inserted.
-"""
-import numpy as np
-import matplotlib.pyplot as plt
-
-t = np.arange(0.0, 1.0 + 0.01, 0.01)
-s = np.cos(2 * 2*np.pi * t)
-t[41:60] = np.nan
-
-plt.subplot(2, 1, 1)
-plt.plot(t, s, '-', lw=2)
-
-plt.xlabel('time (s)')
-plt.ylabel('voltage (mV)')
-plt.title('A sine wave with a gap of NaNs between 0.4 and 0.6')
-plt.grid(True)
-
-plt.subplot(2, 1, 2)
-t[0] = np.nan
-t[-1] = np.nan
-plt.plot(t, s, '-', lw=2)
-plt.title('Also with NaN in first and last point')
-
-plt.xlabel('time (s)')
-plt.ylabel('more nans')
-plt.grid(True)
-
-plt.tight_layout()
-plt.show()