diff --git a/.flake8 b/.flake8
index 3bbcf1ded796..68b0c555fd0a 100644
--- a/.flake8
+++ b/.flake8
@@ -262,3 +262,4 @@ per-file-ignores =
     examples/userdemo/connectionstyle_demo.py: E402
     examples/userdemo/custom_boxstyle01.py: E402
     examples/userdemo/pgf_preamble_sgskip.py: E402
+    examples/widgets/textbox.py: E402
diff --git a/examples/widgets/textbox.py b/examples/widgets/textbox.py
index b3c786014b6c..96d1133686d9 100644
--- a/examples/widgets/textbox.py
+++ b/examples/widgets/textbox.py
@@ -3,11 +3,14 @@
 Textbox
 =======
 
-Allowing text input with the Textbox widget.
+The Textbox widget lets users interactively provide text input, including
+formulas. In this example, the plot is updated using the `.on_submit` method.
+This method triggers the execution of the *submit* function when the
+user presses enter in the textbox or leaves the textbox.
 
-You can use the Textbox widget to let users provide any text that needs to be
-displayed, including formulas. You can use a submit button to create plots
-with the given input.
+Note:  The `matplotlib.widgets.TextBox` widget is different from the following
+static elements: :doc:`/tutorials/text/annotations` and
+:doc:`/gallery/recipes/placing_text_boxes`.
 """
 
 import numpy as np
@@ -18,11 +21,17 @@
 t = np.arange(-2.0, 2.0, 0.001)
 s = t ** 2
 initial_text = "t ** 2"
-l, = plt.plot(t, s, lw=2)
+l, = plt.plot(t, s, lw=2)  # make a plot for the math expression "t ** 2"
 
 
-def submit(text):
-    ydata = eval(text)
+def submit(expression):
+    """
+    Update the plotted function to the new math *expression*.
+
+    *expession* is a string using "t" as its independent variable, e.g.
+    "t ** 3".
+    """
+    ydata = eval(expression)
     l.set_ydata(ydata)
     ax.set_ylim(np.min(ydata), np.max(ydata))
     plt.draw()
@@ -32,3 +41,15 @@ def submit(text):
 text_box.on_submit(submit)
 
 plt.show()
+
+#############################################################################
+#
+# ------------
+#
+# References
+# """"""""""
+#
+# The use of the following functions, methods, classes and modules is shown
+# in this example:
+
+from matplotlib.widgets import TextBox