feat(lsp)!: vim.lsp.inlay_hint.get(), enable(), is_enabled() #25512

refactor!: `vim.lsp.inlay_hint()` -> `vim.lsp.inlay_hint.enable()`

Problem:
The LSP specification allows inlay hints to include tooltips, clickable
label parts, and code actions; but Neovim provides no API to query for
these.

Solution:
Add minimal viable extension point from which plugins can query for
inlay hints in a range, in order to build functionality on top of.

Possible Next Steps
---

- Add `virt_text_idx` field to `vim.fn.getmousepos()` return value, for
  usage in mappings of `<LeftMouse>`, `<C-LeftMouse>`, etc

2 files changed, 48 insertions, 8 deletions

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index b727cff2cd..d70c24bb54 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -856,13 +856,6 @@ get_log_path()                                        *vim.lsp.get_log_path()*
     Return: ~
         (string) path to log file
 
-inlay_hint({bufnr}, {enable})                           *vim.lsp.inlay_hint()*
-    Enable/disable/toggle inlay hints for a buffer
-
-    Parameters: ~
-      • {bufnr}   (integer) Buffer handle, or 0 for current
-      • {enable}  (boolean|nil) true/false to enable/disable, nil to toggle
-
 omnifunc({findstart}, {base})                             *vim.lsp.omnifunc()*
     Implements 'omnifunc' compatible LSP completion.
 
@@ -1470,6 +1463,53 @@ save({lenses}, {bufnr}, {client_id})                 *vim.lsp.codelens.save()*
 
 
 ==============================================================================
+Lua module: vim.lsp.inlay_hint                                *lsp-inlay_hint*
+
+enable({bufnr}, {enable})                        *vim.lsp.inlay_hint.enable()*
+    Enable/disable/toggle inlay hints for a buffer
+
+    Parameters: ~
+      • {bufnr}   (integer|nil) Buffer handle, or 0 or nil for current
+      • {enable}  (boolean|nil) true/nil to enable, false to disable
+
+get({filter})                                       *vim.lsp.inlay_hint.get()*
+    Get the list of inlay hints, (optionally) restricted by buffer, client, or
+    range.
+
+    Example usage: >lua
+        local hint = vim.lsp.inlay_hint.get({ bufnr = 0 })[1] -- 0 for current buffer
+
+        local client = vim.lsp.get_client_by_id(hint.client_id)
+        resolved_hint = client.request_sync('inlayHint/resolve', hint.inlay_hint, 100, 0).result
+        vim.lsp.util.apply_text_edits(resolved_hint.textEdits, 0, client.encoding)
+
+        location = resolved_hint.label[1].location
+        client.request("textDocument/hover", {
+          textDocument = { uri = location.uri },
+          position = location.range.start,
+        })
+<
+
+    Parameters: ~
+      • {filter}  vim.lsp.inlay_hint.get.filter ? Optional filters |kwargs|:
+                  • bufnr (integer?): 0 for current buffer
+                  • range (lsp.Range?)
+
+    Return: ~
+        vim.lsp.inlay_hint.get.ret [] Each list item is a table with the following fields:
+        • bufnr (integer)
+        • client_id (integer)
+        • inlay_hint (lsp.InlayHint)
+
+is_enabled({bufnr})                          *vim.lsp.inlay_hint.is_enabled()*
+    Parameters: ~
+      • {bufnr}  (integer|nil) Buffer handle, or 0 or nil for current
+
+    Return: ~
+        (boolean)
+
+
+==============================================================================
 Lua module: vim.lsp.semantic_tokens                      *lsp-semantic_tokens*
 
 force_refresh({bufnr})               *vim.lsp.semantic_tokens.force_refresh()*
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index ac84f59308..9d531b8efc 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -130,7 +130,7 @@ The following new APIs and features were added.
 
 • LSP
   • LSP method names are available in |vim.lsp.protocol.Methods|.
-  • Implemented LSP inlay hints: |vim.lsp.inlay_hint()|
+  • Implemented LSP inlay hints: |lsp-inlay_hint|
     https://microsoft.github.io/language-server-protocol/specification/#textDocument_inlayHint
   • Implemented pull diagnostic textDocument/diagnostic: |vim.lsp.diagnostic.on_diagnostic()|
     https://microsoft.github.io/language-server-protocol/specification/#textDocument_diagnostic