From 9149d8c239b0fbd0e66f9cf7a6c37e73d594c17e Mon Sep 17 00:00:00 2001
From: David Stansby <dstansby@gmail.com>
Date: Thu, 21 Sep 2017 17:07:30 +0100
Subject: [PATCH] Backport PR #9031: Added RectangleSelector.geometry docstring

Docstring contains details specific to RectangleSelector and does not fully generalize to EllipseSelector.

<!--Thank you so much for your PR! To help us review, fill out the form
to the best of your ability.  Please make use of the development guide at
https://matplotlib.org/devdocs/devel/index.html-->

<!--Provide a general summary of your changes in the title above, for
example "Raises ValueError on Non-Numeric Input to set_xlim".  Please avoid
non-descriptive titles such as "Addresses issue  8576".-->

<!--If you are able to do so, please do not create the
PR out of master, but out of a separate branch.  See
https://matplotlib.org/devel/gitwash/development_workflow.html for
instructions.-->

   PR Summary

<!--Please provide at least 1-2 sentences describing the pull request in
detail.  Why is this change required?  What problem does it solve?-->
Matplotlib documentation is missing details concerning the geometry attribute for RectangleSelector.
This change provides a docstring for said attribute which is specific to RectangleSelector and
not generalizable to EllipseSelector.
<!--If it fixes an open issue, please link to the issue here.-->

   PR Checklist

- [ x] Has Pytest style unit tests
- [ x] Code is PEP 8 compliant
- [ x] New features are documented, with examples if plot related
- [ x] Documentation is sphinx and numpydoc compliant
- [ x] Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
- [x ] Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way

<!--We understand that PRs can sometimes be overwhelming, especially as the
reviews start coming in.  Please let us know if the reviews are unclear or the
recommended next step seems overly demanding , or if you would like help in
addressing a reviewer's comments.  And please ping us if you've been waiting
too long to hear back on your PR.-->
---
 lib/matplotlib/widgets.py | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
index 2c395250b2e5..8b4055643a74 100644
--- a/lib/matplotlib/widgets.py
+++ b/lib/matplotlib/widgets.py
@@ -2334,6 +2334,13 @@ def _set_active_handle(self, event):
 
     @property
     def geometry(self):
+        """
+        Returns numpy.ndarray of shape (2,5) containing
+        x (``RectangleSelector.geometry[1,:]``) and
+        y (``RectangleSelector.geometry[0,:]``)
+        coordinates of the four corners of the rectangle starting
+        and ending in the top left corner.
+        """
         if hasattr(self.to_draw, 'get_verts'):
             xfm = self.ax.transData.inverted()
             y, x = xfm.transform(self.to_draw.get_verts()).T