DOC: clarify when existing figures when switching backend

Author: tacaswell

lib/matplotlib/__init__.py

@@ -1124,6 +1124,10 @@ def use(backend, *, force=True):
     """
     Select the backend used for rendering and GUI integration.
 
+    If pyplot is already imported, `~matplotlib.pyplot.switch_backend` is used
+    and if the new backend is different than the current backend, all Figures
+    will be closed.
+
     Parameters
     ----------
     backend : str
@@ -1154,6 +1158,8 @@ def use(backend, *, force=True):
     --------
     :ref:`backends`
     matplotlib.get_backend
+    matplotlib.pyplot.switch_backend
+
     """
     name = validate_backend(backend)
     # don't (prematurely) resolve the "auto" backend setting

lib/matplotlib/pyplot.py

@@ -210,16 +210,20 @@ def _get_backend_mod():
 
 def switch_backend(newbackend):
     """
-    Close all open figures and set the Matplotlib backend.
+    Set the pyplot backend.
 
-    The argument is case-insensitive.  Switching to an interactive backend is
-    possible only if no event loop for another interactive backend has started.
-    Switching to and from non-interactive backends is always possible.
+    Switching to an interactive backend is possible only if no event loop for
+    another interactive backend has started.  Switching to and from
+    non-interactive backends is always possible.
+
+    If the new backend is different than the current backend then all open
+    Figures will be closed via ``plt.close('all')``.
 
     Parameters
     ----------
     newbackend : str
-        The name of the backend to use.
+        The case-insensitive name of the backend to use.
+
     """
     global _backend_mod
     # make sure the init is pulled up so we can assign to it later