Merge #8580

8580: Remove confusion around serverStatusNotification r=matklad a=matklad

bors r+
🤖

Co-authored-by: Aleksey Kladov <[email protected]>

1 files changed, 8 insertions, 3 deletions

diff --git a/docs/dev/lsp-extensions.md b/docs/dev/lsp-extensions.md
index fff11e12e..f0f981802 100644
--- a/docs/dev/lsp-extensions.md
+++ b/docs/dev/lsp-extensions.md
@@ -433,11 +433,13 @@ interface ServerStatusParams {
     /// `ok` means that the server is completely functional.
     ///
     /// `warning` means that the server is partially functional.
-    /// It can server requests, but some results might be wrong due to,
-    /// for example, some missing dependencies.
+    /// It can answer correctly to most requests, but some results
+    /// might be wrong due to, for example, some missing dependencies.
     ///
     /// `error` means that the server is not functional. For example,
-    /// there's a fatal build configuration problem.
+    /// there's a fatal build configuration problem. The server might
+    /// still give correct answers to simple requests, but most results
+    /// will be incomplete or wrong.
     health: "ok" | "warning" | "error",
     /// Is there any pending background work which might change the status?
     /// For example, are dependencies being downloaded?
@@ -451,6 +453,9 @@ This notification is sent from server to client.
 The client can use it to display *persistent* status to the user (in modline).
 It is similar to the `showMessage`, but is intended for stares rather than point-in-time events.
 
+Note that this functionality is intended primarily to inform the end user about the state of the server.
+In particular, it's valid for the client to completely ignore this extension.
+Clients are discouraged from but are allowed to use the `health` status to decide if it's worth sending a request to the server.
 
 ## Syntax Tree