Improve documentation

ericpre · ericpre · commit c394be82bfc1 · 2021-12-04T19:10:09.000Z
diff --git a/doc/users/next_whats_new/selector_improvement.rst b/doc/users/next_whats_new/selector_improvement.rst
@@ -4,16 +4,16 @@ Selectors improvement: rotation, aspect ratio correction and add/remove state
 The `~matplotlib.widgets.RectangleSelector` and
 `~matplotlib.widgets.EllipseSelector` can now be rotated interactively.
 The rotation is enabled or disable by striking the *r* key
-(default value of 'rotate' in *state_modifier_keys*) or by calling
-*selector.add_state('rotate')*.
+('r' is the default key mapped to 'rotate' in *state_modifier_keys*) or by calling
+``selector.add_state('rotate')``.
 
 The aspect ratio of the axes can now be taken into account when using the
-"square" state. This is enable by specifying *use_data_coordinates='True'* when
+"square" state. This is enabled by specifying ``use_data_coordinates='True'`` when
 the selector is initialized.
 
 In addition to changing selector state interactively using the modifier keys
 defined in *state_modifier_keys*, the selector state can now be changed
-programmatically using the *add_state* and *remove_state* method.
+programmatically using the *add_state* and *remove_state* methods.
 
 
 .. code-block:: python
diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
@@ -780,6 +780,7 @@ def get_patch_transform(self):
 
     @property
     def rotation_point(self):
+        """The rotation point of the patch."""
         return self._rotation_point
 
     @rotation_point.setter
diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
@@ -2074,37 +2074,34 @@ def set_handle_props(self, **handle_props):
             self.update()
         self._handle_props.update(handle_props)
 
-    def _validate_state(self, value):
+    def _validate_state(self, state):
         supported_state = [
             key for key, value in self._state_modifier_keys.items()
             if key != 'clear' and value != 'not-applicable'
             ]
-        if value not in supported_state:
-            keys = ', '.join(supported_state)
-            raise ValueError('Setting default state must be one of the '
-                             f'following: {keys}.')
+        _api.check_in_list(supported_state, state=state)
 
-    def add_state(self, value):
+    def add_state(self, state):
         """
         Add a state to define the widget's behavior. See the
         `state_modifier_keys` parameters for details.
 
         Parameters
         ----------
-        value : str
+        state : str
             Must be a supported state of the selector. See the
             `state_modifier_keys` parameters for details.
 
         Raises
         ------
         ValueError
-            When the value is not supported by the selector.
+            When the state is not supported by the selector.
 
         """
-        self._validate_state(value)
-        self._state.add(value)
+        self._validate_state(state)
+        self._state.add(state)
 
-    def remove_state(self, value):
+    def remove_state(self, state):
         """
         Remove a state to define the widget's behavior. See the
         `state_modifier_keys` parameters for details.
@@ -2118,11 +2115,11 @@ def remove_state(self, value):
         Raises
         ------
         ValueError
-            When the value is not supported by the selector.
+            When the state is not supported by the selector.
 
         """
-        self._validate_state(value)
-        self._state.remove(value)
+        self._validate_state(state)
+        self._state.remove(state)
 
 
 class SpanSelector(_SelectorWidget):
@@ -2193,7 +2190,7 @@ def on_select(min: float, max: float) -> Any
 
     state_modifier_keys : dict, optional
         Keyboard modifiers which affect the widget's behavior.  Values
-        amend the defaults.
+        amend the defaults, which are:
 
         - "clear": Clear the current shape, default: "escape".
 
@@ -2800,7 +2797,7 @@ def onselect(eclick: MouseEvent, erelease: MouseEvent)
 
     state_modifier_keys : dict, optional
         Keyboard modifiers which affect the widget's behavior.  Values
-        amend the defaults.
+        amend the defaults, which are:
 
         - "move": Move the existing shape, default: no modifier.
         - "clear": Clear the current shape, default: "escape".
@@ -2855,6 +2852,8 @@ class RectangleSelector(_SelectorWidget):
                                           props=props)
     >>> fig.show()
 
+    >>> selector.add_state('square')
+
     See also: :doc:`/gallery/widgets/rectangle_selector`
     """
 
