Clarify when activate-mark-hook is run

* doc/lispref/markers.texi (The Mark):
* lisp/simple.el (activate-mark-hook): Clarify when the hook is
run (bug#23444).

2 files changed, 5 insertions, 4 deletions

diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi
index cdd0938b458..93f98190fa3 100644
--- a/doc/lispref/markers.texi
+++ b/doc/lispref/markers.texi
@@ -607,8 +607,8 @@ the function @code{use-region-p} for that (@pxref{The Region}).
 @defvarx deactivate-mark-hook
 These normal hooks are run, respectively, when the mark becomes active
 and when it becomes inactive.  The hook @code{activate-mark-hook} is
-also run at the end of the command loop if the mark is active and it
-is possible that the region may have changed.
+also run when the region is reactivated, for instance after using a
+command that switches back to a buffer that has an active mark.
 @ignore
 This piece of command_loop_1, run unless deactivating the mark:
   if (current_buffer != prev_buffer || MODIFF != prev_modiff)
diff --git a/lisp/simple.el b/lisp/simple.el
index 10cde4e4b89..28738a262d3 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -5536,8 +5536,9 @@ START and END specify the portion of the current buffer to be copied."
 
 (defvar activate-mark-hook nil
   "Hook run when the mark becomes active.
-It is also run at the end of a command, if the mark is active and
-it is possible that the region may have changed.")
+It is also run when the region is reactivated, for instance after
+using a command that switches back to a buffer that has an active
+mark.")
 
 (defvar deactivate-mark-hook nil
   "Hook run when the mark becomes inactive.")