docs(lsp): hover window controls #30347

2 files changed, 11 insertions, 2 deletions

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index e820d54a9e..3bc2256064 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -1397,7 +1397,11 @@ format({opts})                                          *vim.lsp.buf.format()*
 
 hover()                                                  *vim.lsp.buf.hover()*
     Displays hover information about the symbol under the cursor in a floating
-    window. Calling the function twice will jump into the floating window.
+    window. The window will be dismissed on cursor move. Calling the function
+    twice will jump into the floating window (thus by default, "KK" will open
+    the hover window and focus it). In the floating window, all commands and
+    mappings are available as usual, except that "q" dismisses the window. You
+    can scroll the contents the same as you would any other buffer.
 
 implementation({opts})                          *vim.lsp.buf.implementation()*
     Lists all the implementations for the symbol under the cursor in the
diff --git a/runtime/lua/vim/lsp/buf.lua b/runtime/lua/vim/lsp/buf.lua
index a43ad8a690..301c1f0cb6 100644
--- a/runtime/lua/vim/lsp/buf.lua
+++ b/runtime/lua/vim/lsp/buf.lua
@@ -29,7 +29,12 @@ local function request(method, params, handler)
 end
 
 --- Displays hover information about the symbol under the cursor in a floating
---- window. Calling the function twice will jump into the floating window.
+--- window. The window will be dismissed on cursor move.
+--- Calling the function twice will jump into the floating window
+--- (thus by default, "KK" will open the hover window and focus it).
+--- In the floating window, all commands and mappings are available as usual,
+--- except that "q" dismisses the window.
+--- You can scroll the contents the same as you would any other buffer.
 function M.hover()
   local params = util.make_position_params()
   request(ms.textDocument_hover, params)