* src/keyboard.c (post-command-hook): Extend the docstring

Mainly, explain how to use it without hanging Emacs, or giving the
impression that it is hanging.  Also mention `pre-command-hook'.

(pre-command-hook): Mention `post-command-hook'.

1 files changed, 14 insertions, 2 deletions

diff --git a/src/keyboard.c b/src/keyboard.c
index 1a78f6a705c..4ea0f97e77f 100644
--- a/src/keyboard.c
+++ b/src/keyboard.c
@@ -11374,14 +11374,26 @@ Buffer modification stores t in this variable.  */);
                doc: /* Normal hook run before each command is executed.
 If an unhandled error happens in running this hook,
 the function in which the error occurred is unconditionally removed, since
-otherwise the error might happen repeatedly and make Emacs nonfunctional.  */);
+otherwise the error might happen repeatedly and make Emacs nonfunctional.
+
+See also `pre-command-hook'.  */);
   Vpre_command_hook = Qnil;
 
   DEFVAR_LISP ("post-command-hook", Vpost_command_hook,
                doc: /* Normal hook run after each command is executed.
 If an unhandled error happens in running this hook,
 the function in which the error occurred is unconditionally removed, since
-otherwise the error might happen repeatedly and make Emacs nonfunctional.  */);
+otherwise the error might happen repeatedly and make Emacs nonfunctional.
+
+It is usually a bad idea to use this hook for expensive processing.
+If unavoidable, `while-no-input' can be used avoid making Emacs
+unresponsive while the user types.  Furthermore, this hook is run
+before redisplay, so the effect of the executed command won't be
+displayed on the buffer until after the hook has finished (giving the
+impression that Emacs is hanging).  You can call `redisplay' inside
+`while-no-input' to avoid this.
+
+See also `pre-command-hook'.  */);
   Vpost_command_hook = Qnil;
 
 #if 0