Add explanatory comments for text rotation example

mollyrossow · mollyrossow · commit 138145aebced · 2019-02-19T11:34:42.000-06:00
diff --git a/examples/text_labels_and_annotations/demo_text_rotation_mode.py b/examples/text_labels_and_annotations/demo_text_rotation_mode.py
@@ -1,9 +1,15 @@
-"""
-=======================
+"""=======================
 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.
+
 """
+import matplotlib
 from mpl_toolkits.axes_grid1.axes_grid import ImageGrid
 
 
@@ -19,18 +25,23 @@ 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:
             ax = grid[i]
             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.",
@@ -48,3 +59,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:
+
+
+matplotlib.axes.Axes.text
