Improve documentation, docstring and comments

Author: ericpre

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.

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

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.