Improve documentation, docstring and comments

ericpre · ericpre · commit 1d02de77dc3f · 2021-11-15T22:37:54.000Z
diff --git a/doc/api/next_api_changes/deprecations/20839-EP.rst b/doc/api/next_api_changes/deprecations/20839-EP.rst
@@ -1,4 +1,4 @@
 Selector widget state internals
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-*state_modifier_keys* have to be defined when creating the selector widget. The 
-*state_modifier_keys* attribute is deprecated.
+*state_modifier_keys* now have to be defined when creating a selector widget.
+The *state_modifier_keys* attribute is deprecated.
diff --git a/doc/users/next_whats_new/rectangleselector_square_center.rst b/doc/users/next_whats_new/rectangleselector_square_center.rst
@@ -2,6 +2,6 @@ Rectangle selector square shape and centering
 ---------------------------------------------
 
 When changing an existing `~matplotlib.widgets.RectangleSelector` interactively,
-the shape can now be kept square or changed around its center. The square shape
-can be defined in data or figure coordinates as determined by the
-``data_coordinates`` modifier.
+the shape can now be kept square or rotated/resized around its center.
+The square shape can be defined in data or display coordinate system as defined
+by the *data_coordinates* modifier.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -8096,7 +8096,10 @@ def violin(self, vpstats, positions=None, vert=True, widths=0.5,
     triplot = mtri.triplot
 
     def _get_aspect_ratio(self):
-        """Convenience method to calculate aspect ratio of the axes."""
+        """
+        Convenience method to calculate the aspect ratio of the axes in
+        the display coordinate system.
+        """
         figure_size = self.get_figure().get_size_inches()
         ll, ur = self.get_position() * figure_size
         width, height = ur - ll
diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
@@ -738,6 +738,10 @@ def __init__(self, xy, width, height, angle=0.0,
         self.angle = float(angle)
         self.rotate_around_center = rotate_around_center
         # Required for RectangleSelector with axes aspect ratio != 1
+        # The patch is defined in data coordinates and when changing the
+        # selector with square modifier and not in data coordinates, we need
+        # to correct for the aspect ratio difference between the data and
+        # display coordinate systems.
         self._aspect_ratio_correction = 1.0
         self._convert_units()  # Validate the inputs.
 
