Clarify docstring of [un]install_repl_displayhook()

timhoffm · timhoffm · commit 618ecc91b882 · 2022-04-27T23:49:06.000+02:00
Still not clear to me: Does this have to be a public function? When
would a user call it explicitly?
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -114,8 +114,11 @@ def _copy_docstring_and_deprecators(method, func=None):
 
 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.
     """
@@ -152,15 +155,7 @@ def post_execute():
 
 
 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 _IP_REGISTERED
     global _INSTALL_FIG_OBSERVER
     if _IP_REGISTERED:
