From 83701e9e10574215c4400685941c6d83f03c012c Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Tue, 26 Apr 2022 23:05:02 +0200
Subject: [PATCH] Clarify docstring of [un]install_repl_displayhook()

Still not clear to me: Does this have to be a public function? When
would a user call it explicitly?
---
 lib/matplotlib/pyplot.py | 17 ++++++-----------
 1 file changed, 6 insertions(+), 11 deletions(-)

diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
index 47a3122ac3d9..577956bedce6 100644
--- a/lib/matplotlib/pyplot.py
+++ b/lib/matplotlib/pyplot.py
@@ -122,8 +122,11 @@ def _draw_all_if_interactive():
 
 def install_repl_displayhook():
     """
-    Install a repl display hook so that any stale figure are automatically
-    redrawn when control is returned to the repl.
+    Connect to the display hook of the current shell.
+
+    The display hook gets called when the read-evaluate-print-loop (REPL) of
+    the shell has finished the execution of a command. We use this callback
+    to be able to automatically update a figure in interactive mode.
 
     This works both with IPython and with vanilla python shells.
     """
@@ -155,15 +158,7 @@ def install_repl_displayhook():
 
 
 def uninstall_repl_displayhook():
-    """
-    Uninstall the Matplotlib display hook.
-
-    .. warning::
-
-       If you are using vanilla python and have installed another display hook,
-       this will reset `sys.displayhook` to what ever function was there when
-       Matplotlib installed its displayhook, possibly discarding your changes.
-    """
+    """Disconnect from the display hook of the current shell."""
     global _REPL_DISPLAYHOOK
     if _REPL_DISPLAYHOOK is _ReplDisplayHook.IPYTHON:
         from IPython import get_ipython