[Emacs-diffs] master 12941b9 2/2: * src/keyboard.c (post-command-hook): Extend the docstring

[Artur Malabarba]

branch: master
commit 12941b99d16835b5de3f065545ebe6a0835a1d0f
Author: Artur Malabarba <address@hidden>
Commit: Artur Malabarba <address@hidden>

    * 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'.
---
 src/keyboard.c |   16 ++++++++++++++--
 1 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/src/keyboard.c b/src/keyboard.c
index 1a78f6a..4ea0f97 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