emacs-27 4712c75: Clarify when activate-mark-hook is run

[Lars Ingebrigtsen]

branch: emacs-27
commit 4712c75ab853ee77587dbc1910cc7c0401e02aa0
Author: Lars Ingebrigtsen <larsi@gnus.org>
Commit: Lars Ingebrigtsen <larsi@gnus.org>

    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).
---
 doc/lispref/markers.texi | 4 ++--
 lisp/simple.el           | 5 +++--
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi
index cdd0938..93f9819 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 10cde4e..28738a2 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.")