DOC: add docstring to close

Author: tacaswell

mpl_gui/__init__.py

@@ -252,6 +252,37 @@ def close_all(self):
             self.close(fig)
 
     def close(self, val):
+        """
+        Close (meaning destroy the UI) and forget a managed Figure.
+
+        This will do two things:
+
+        - start the destruction process of an UI (the event loop may need to
+          run to complete this process and if the user is holding hard
+          references to any of the UI elements they may remain alive).
+        - Remove the `Figure` from this Registry.
+
+        We will no longer have any hard references to the Figure, but if
+        the user does the `Figure` (and its components) will not be garbage
+        collected.  Due to the circular references in Matplotlib these
+        objects may not be collected until the full cyclic garbage collection
+        runs.
+
+        If the user still has a reference to the `Figure` they can re-show the
+        figure via `show`, but the `FigureRegistry` will not be aware of it.
+
+        Parameters
+        ----------
+        val : 'all' or int or str or Figure
+
+            - The special case of 'all' closes all open Figures
+            - If any other string is passed, it is interpreted as a key in
+              `by_label` and that Figure is closed
+            - If an integer it is interpreted as a key in `by_number` and that
+              Figure is closed
+            - If it is a `Figure` instance, then that figure is closed
+
+        """
         if val == "all":
             return self.close_all()
         # or do we want to close _all_ of the figures with a given label / number?
@@ -261,12 +292,17 @@ def close(self, val):
             fig = self.by_number[val]
         else:
             fig = val
+            if fig not in self.figures:
+                raise ValueError(
+                    "Trying to close a figure not associated with this Registry."
+                )
         if fig.canvas.manager is not None:
             fig.canvas.manager.destroy()
             # disconnect figure from canvas
             fig.canvas.figure = None
             # disconnect canvas from figure
             _FigureCanvasBase(figure=fig)
+        assert fig.canvas.manager is None
         if fig in self.figures:
             self.figures.remove(fig)