; Clarify documentation of 'server-after-make-frame-hook'

* doc/lispref/frames.texi (Creating Frames):
* lisp/server.el (server-after-make-frame-hook): Clarify
documentation of 'server-after-make-frame-hook'.  (Bug#64873)

2 files changed, 11 insertions, 5 deletions

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 5a2d9f29295..368def90d85 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -187,9 +187,13 @@ selected frame.
 @end defvar
 
 @defopt server-after-make-frame-hook
-A normal hook run when the Emacs server creates a client frame.  When
-this hook is called, the created frame is the selected one.
-@xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
+A normal hook run when the Emacs server starts using a client frame.
+When this hook is called, the client frame is the selected one.  Note
+that, depending on how @command{emacsclient} was invoked
+(@pxref{Invoking emacsclient,,, emacs, The GNU Emacs Manual}), this
+client frame could be a new frame created for the client, or it could
+be an existing frame that the server reused for handling the client
+commands.  @xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
 @end defopt
 
 
diff --git a/lisp/server.el b/lisp/server.el
index c3325e5a24c..ba7e02d2555 100644
--- a/lisp/server.el
+++ b/lisp/server.el
@@ -182,8 +182,10 @@ space (this means characters from ! to ~; or from code 33 to
   :type 'hook)
 
 (defcustom server-after-make-frame-hook nil
-  "Hook run when the Emacs server creates a client frame.
-The created frame is selected when the hook is called."
+  "Hook run when the Emacs server starts using a client frame.
+The client frame is selected when the hook is called.
+The client frame could be a newly-created frame, or an
+existing frame reused for this purpose."
   :type 'hook
   :version "27.1")