diff --git a/.flake8 b/.flake8
index 611538d1ee34..cc5766c08431 100644
--- a/.flake8
+++ b/.flake8
@@ -253,6 +253,7 @@ per-file-ignores =
     examples/subplots_axes_and_figures/zoom_inset_axes.py: E402
     examples/tests/backend_driver_sgskip.py: E402, E501
     examples/text_labels_and_annotations/annotation_demo.py: E501
+    examples/text_labels_and_annotations/demo_text_rotation_mode.py: E402 
     examples/text_labels_and_annotations/custom_legends.py: E402
     examples/text_labels_and_annotations/font_family_rc_sgskip.py: E402
     examples/text_labels_and_annotations/font_file.py: E402
diff --git a/examples/text_labels_and_annotations/demo_text_rotation_mode.py b/examples/text_labels_and_annotations/demo_text_rotation_mode.py
index 8fc0f6e1ecbd..117132c89e16 100644
--- a/examples/text_labels_and_annotations/demo_text_rotation_mode.py
+++ b/examples/text_labels_and_annotations/demo_text_rotation_mode.py
@@ -1,8 +1,14 @@
-"""
-=======================
+"""=======================
 Demo Text Rotation Mode
 =======================
 
+The axes' method `~.axes.Axes.text` takes an argument ``rotation_mode`` that
+controls the alignment and rotation of the text. If ``rotation_mode`` is
+``None`` or ``default`` the text will first be rotated and then aligned
+according to the horizontal and vertical alignments (``ha`` and ``va`` in the
+example). If ``rotation_mode`` is ``anchor`` the text is aligned before
+rotation.
+
 """
 from mpl_toolkits.axes_grid1.axes_grid import ImageGrid
 
@@ -19,11 +25,14 @@ def test_rotation_mode(fig, mode, subplot_location):
     for ha, ax in zip(ha_list, grid.axes_row[-1]):
         ax.axis["bottom"].label.set_text(ha)
 
+    # create a grid of axes to display text on.
     grid.axes_row[0][1].set_title(mode, size="large")
 
     for va, ax in zip(va_list, grid.axes_column[0]):
         ax.axis["left"].label.set_text(va)
 
+    # use a different horizontal and vertical alignment for the text in each
+    # axes.
     i = 0
     for va in va_list:
         for ha in ha_list:
@@ -31,6 +40,8 @@ def test_rotation_mode(fig, mode, subplot_location):
             for axis in ax.axis.values():
                 axis.toggle(ticks=False, ticklabels=False)
 
+            # add text to the axes. Set the rotation_mode, horizontal
+            # alignment (ha) and vertical alignment (va).
             ax.text(0.5, 0.5, "Tpg",
                     size="large", rotation=40,
                     bbox=dict(boxstyle="square,pad=0.",
@@ -50,3 +61,16 @@ def test_rotation_mode(fig, mode, subplot_location):
     test_rotation_mode(fig, "default", 121)
     test_rotation_mode(fig, "anchor", 122)
     plt.show()
+
+
+#############################################################################
+#
+# ------------
+#
+# References
+# """"""""""
+#
+# The use of the following method is shown in this example:
+
+import matplotlib
+matplotlib.axes.Axes.text