feat(lsp): map K to hover by default #24331

Related: https://github.com/neovim/neovim/issues/24252

5 files changed, 40 insertions, 2 deletions

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 3aef5bb7dd..450690fe3b 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -58,6 +58,8 @@ options are not restored when the LSP client is stopped or detached.
 - 'formatexpr' is set to |vim.lsp.formatexpr()|, so you can format lines via
   |gq| if the language server supports it.
   - To opt out of this use |gw| instead of gq, or set 'formatexpr' on LspAttach.
+- |K| is mapped to |vim.lsp.buf.hover()| unless |'keywordprg'| is customized or
+  a custom keymap for `K` exists.
 
                                                         *lsp-defaults-disable*
 To override the above defaults, set or unset the options on |LspAttach|: >lua
@@ -65,6 +67,7 @@ To override the above defaults, set or unset the options on |LspAttach|: >lua
       callback = function(ev)
         vim.bo[ev.buf].formatexpr = nil
         vim.bo[ev.buf].omnifunc = nil
+        vim.keymap.del("n", "K", { bufnr = ev.buf })
       end,
     })
 
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 51ff0b4468..e16bcafac2 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -156,6 +156,10 @@ The following changes to existing APIs or features add new behavior.
   `vim.ui.open` or remap `gx`. To continue using netrw (deprecated): >vim
   :call netrw#BrowseX(expand(exists("g:netrw_gx")? g:netrw_gx : '<cfile>'), netrw#CheckIfRemote())<CR>
 
+• |vim.lsp.start()| now maps |K| to use |vim.lsp.buf.hover()| if the server
+  supports it, unless |'keywordprg'| was customized before calling
+  |vim.lsp.start()|.
+
 ==============================================================================
 REMOVED FEATURES                                                 *news-removed*
 
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
index 1f9b6c4360..e9a1423d2d 100644
--- a/runtime/lua/vim/lsp.lua
+++ b/runtime/lua/vim/lsp.lua
@@ -963,6 +963,15 @@ function lsp._set_defaults(client, bufnr)
   then
     vim.bo[bufnr].formatexpr = 'v:lua.vim.lsp.formatexpr()'
   end
+  api.nvim_buf_call(bufnr, function()
+    if
+      client.supports_method('textDocument/hover')
+      and is_empty_or_default(bufnr, 'keywordprg')
+      and vim.fn.maparg('K', 'n', false, false) == ''
+    then
+      vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = bufnr })
+    end
+  end)
 end
 
 --- @class lsp.ClientConfig
@@ -1202,7 +1211,7 @@ function lsp.start_client(config)
   ---@private
   --- Reset defaults set by `set_defaults`.
   --- Must only be called if the last client attached to a buffer exits.
-  local function unset_defaults(bufnr)
+  local function reset_defaults(bufnr)
     if vim.bo[bufnr].tagfunc == 'v:lua.vim.lsp.tagfunc' then
       vim.bo[bufnr].tagfunc = nil
     end
@@ -1212,6 +1221,12 @@ function lsp.start_client(config)
     if vim.bo[bufnr].formatexpr == 'v:lua.vim.lsp.formatexpr()' then
       vim.bo[bufnr].formatexpr = nil
     end
+    api.nvim_buf_call(bufnr, function()
+      local keymap = vim.fn.maparg('K', 'n', false, true)
+      if keymap and keymap.callback == vim.lsp.buf.hover then
+        vim.keymap.del('n', 'K', { buffer = bufnr })
+      end
+    end)
   end
 
   ---@private
@@ -1243,7 +1258,7 @@ function lsp.start_client(config)
 
           client_ids[client_id] = nil
           if vim.tbl_isempty(client_ids) then
-            unset_defaults(bufnr)
+            reset_defaults(bufnr)
           end
         end)
       end
diff --git a/test/functional/fixtures/fake-lsp-server.lua b/test/functional/fixtures/fake-lsp-server.lua
index 6ee9dac2ca..ef87f6c21a 100644
--- a/test/functional/fixtures/fake-lsp-server.lua
+++ b/test/functional/fixtures/fake-lsp-server.lua
@@ -939,6 +939,7 @@ function tests.set_defaults_all_capabilities()
           definitionProvider = true,
           completionProvider = true,
           documentRangeFormattingProvider = true,
+          hoverProvider = true,
         }
       }
     end;
diff --git a/test/functional/plugin/lsp_spec.lua b/test/functional/plugin/lsp_spec.lua
index 8eced4bfb5..38176c8749 100644
--- a/test/functional/plugin/lsp_spec.lua
+++ b/test/functional/plugin/lsp_spec.lua
@@ -365,6 +365,14 @@ describe('LSP', function()
             eq('v:lua.vim.lsp.tagfunc', get_buf_option("tagfunc"))
             eq('v:lua.vim.lsp.omnifunc', get_buf_option("omnifunc"))
             eq('v:lua.vim.lsp.formatexpr()', get_buf_option("formatexpr"))
+            eq('', get_buf_option("keywordprg"))
+            eq(true, exec_lua[[
+              local keymap
+              vim.api.nvim_buf_call(BUFFER, function()
+                keymap = vim.fn.maparg("K", "n", false, true)
+              end)
+              return keymap.callback == vim.lsp.buf.hover
+            ]])
             client.stop()
           end
         end;
@@ -372,6 +380,13 @@ describe('LSP', function()
           eq('', get_buf_option("tagfunc"))
           eq('', get_buf_option("omnifunc"))
           eq('', get_buf_option("formatexpr"))
+          eq('', exec_lua[[
+            local keymap
+            vim.api.nvim_buf_call(BUFFER, function()
+              keymap = vim.fn.maparg("K", "n", false, false)
+            end)
+            return keymap
+          ]])
         end;
       }
     end)