From e269cb3d16806f1e7c84b275b6960da1cce9ce89 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Jo=C3=A3o=20T=C3=A1vora?= <joaotavora@gmail.com>
Date: Wed, 9 Oct 2024 06:26:27 -0500
Subject: [PATCH] Eglot: minor changes to doc and docstrings

* doc/misc/eglot.texi (Quick Start): Tweak.
(Setting Up LSP Servers): Tweak.
(Customizing Eglot): Clarify eglot-connect-hook and
eglot-initialized-hook.

* lisp/progmodes/eglot.el (eglot-connect-hook)
(eglot-server-initialized-hook): Rework docstring.

(cherry picked from commit cd36e070c24d7828ea1b9bf62ffa920068ac4d41)
---
 doc/misc/eglot.texi     | 28 +++++++++++++++++-----------
 lisp/progmodes/eglot.el |  9 ++++++---
 2 files changed, 23 insertions(+), 14 deletions(-)

diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi
index fb5b618bd84..959bbfa6857 100644
--- a/doc/misc/eglot.texi
+++ b/doc/misc/eglot.texi
@@ -123,14 +123,16 @@ Here's how to start using Eglot with your programming project:
 @item
 Select and install a language server.
 
-Eglot comes pre-configured with many popular language servers, see the
-value of @code{eglot-server-programs}.  If the server(s) mentioned
-there satisfy your needs for the programming language(s) with which
-you want to use Eglot, you just need to make sure those servers are
-installed on your system.  Alternatively, install one or more servers
-of your choice and add them to the value of
+Eglot comes pre-configured for many popular language servers, see the
+value of @code{eglot-server-programs}.  If the server(s) mentioned there
+satisfy your needs for the programming language(s) with which you want
+to use Eglot, you just need to make sure those servers are installed on
+your system and Eglot can find them.
+
+Alternatively, install one or more servers of your choice and tell Eglot
+where to find them.  To do that, you may add to the value of
 @code{eglot-server-programs}, as described in @ref{Setting Up LSP
-Servers}.
+Servers} or have Eglot prompt you about it (@pxref{Eglot Commands}).
 
 @item
 Turn on Eglot for your project.
@@ -197,7 +199,7 @@ particular server(s) you want to install.
 
 To use a language server, Eglot must know how to start it and which
 programming languages each server supports.  This information is
-provided by the variable @code{eglot-server-programs}.
+commonly provided by the variable @code{eglot-server-programs}.
 
 @defvar eglot-server-programs
 This variable associates major modes with names and command-line
@@ -939,12 +941,16 @@ to @w{@code{(disallow-non-standard-keys enforce-required-keys)}}.
 
 @vindex eglot-server-initialized-hook
 @item eglot-server-initialized-hook
-A hook run after the server object is successfully initialized.
+A hook run after the server object is successfully initialized (which
+includes launching the process) but before any LSP communication is
+attempted.  Each function receives a @code{eglot-lsp-server} instance as
+argument.
 
 @vindex eglot-connect-hook
 @item eglot-connect-hook
-A hook run after connection to the server is successfully
-established.  @xref{Starting Eglot}.
+A hook run after the LSP connection to the server is successfully
+established.  Each function receives a @code{eglot-lsp-server} instance
+as argument.  @xref{Starting Eglot}.
 
 @item eglot-managed-mode-hook
 A hook run after Eglot started or stopped managing a buffer.
diff --git a/lisp/progmodes/eglot.el b/lisp/progmodes/eglot.el
index d2ab8876c64..51075324632 100644
--- a/lisp/progmodes/eglot.el
+++ b/lisp/progmodes/eglot.el
@@ -1480,18 +1480,21 @@ Use current server's or first available Eglot events buffer."
 
 (defvar eglot-connect-hook
   '(eglot-signal-didChangeConfiguration)
-  "Hook run after connecting in `eglot--connect'.")
+  "Hook run after connecting to a server.
+Each function is passed an `eglot-lsp-server' instance
+as argument.")
 
 (defvar eglot-server-initialized-hook
   '()
   "Hook run after a `eglot-lsp-server' instance is created.
 
-That is before a connection was established.  Use
+That is before a connection is established.  Use
 `eglot-connect-hook' to hook into when a connection was
 successfully established and the server on the other side has
 received the initializing configuration.
 
-Each function is passed the server as an argument")
+Each function is passed an `eglot-lsp-server' instance
+as argument.")
 
 (defun eglot--cmd (contact)
   "Helper for `eglot--connect'."
-- 
2.39.5