fix(lsp): semantic token functions allow "0" bufnr #28849

aligns with ":help dev-patterns"

3 files changed, 83 insertions, 14 deletions

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index ab09ba4252..5729531b30 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -1686,9 +1686,10 @@ highlight_token({token}, {bufnr}, {client_id}, {hl_group}, {opts})
     use inside |LspTokenUpdate| callbacks.
 
     Parameters: ~
-      • {token}      (`table`) a semantic token, found as `args.data.token` in
-                     |LspTokenUpdate|.
-      • {bufnr}      (`integer`) the buffer to highlight
+      • {token}      (`table`) A semantic token, found as `args.data.token` in
+                     |LspTokenUpdate|
+      • {bufnr}      (`integer`) The buffer to highlight, or `0` for current
+                     buffer
       • {client_id}  (`integer`) The ID of the |vim.lsp.Client|
       • {hl_group}   (`string`) Highlight group name
       • {opts}       (`table?`) Optional parameters:
@@ -1709,8 +1710,8 @@ start({bufnr}, {client_id}, {opts})          *vim.lsp.semantic_tokens.start()*
 <
 
     Parameters: ~
-      • {bufnr}      (`integer`)
-      • {client_id}  (`integer`)
+      • {bufnr}      (`integer`) Buffer number, or `0` for current buffer
+      • {client_id}  (`integer`) The ID of the |vim.lsp.Client|
       • {opts}       (`table?`) Optional keyword arguments
                      • debounce (integer, default: 200): Debounce token
                        requests to the server by the given number in
@@ -1726,8 +1727,8 @@ stop({bufnr}, {client_id})                    *vim.lsp.semantic_tokens.stop()*
     from the buffer.
 
     Parameters: ~
-      • {bufnr}      (`integer`)
-      • {client_id}  (`integer`)
+      • {bufnr}      (`integer`) Buffer number, or `0` for current buffer
+      • {client_id}  (`integer`) The ID of the |vim.lsp.Client|
 
 
 ==============================================================================
diff --git a/runtime/lua/vim/lsp/semantic_tokens.lua b/runtime/lua/vim/lsp/semantic_tokens.lua
index be2d6ee0ae..ef2502b12e 100644
--- a/runtime/lua/vim/lsp/semantic_tokens.lua
+++ b/runtime/lua/vim/lsp/semantic_tokens.lua
@@ -570,9 +570,9 @@ local M = {}
 --- client.server_capabilities.semanticTokensProvider = nil
 --- ```
 ---
----@param bufnr integer
----@param client_id integer
----@param opts? table Optional keyword arguments
+---@param bufnr (integer) Buffer number, or `0` for current buffer
+---@param client_id (integer) The ID of the |vim.lsp.Client|
+---@param opts? (table) Optional keyword arguments
 ---  - debounce (integer, default: 200): Debounce token requests
 ---        to the server by the given number in milliseconds
 function M.start(bufnr, client_id, opts)
@@ -581,6 +581,10 @@ function M.start(bufnr, client_id, opts)
     client_id = { client_id, 'n', false },
   })
 
+  if bufnr == 0 then
+    bufnr = api.nvim_get_current_buf()
+  end
+
   opts = opts or {}
   assert(
     (not opts.debounce or type(opts.debounce) == 'number'),
@@ -626,14 +630,18 @@ end
 --- of `start()`, so you should only need this function to manually disengage the semantic
 --- token engine without fully detaching the LSP client from the buffer.
 ---
----@param bufnr integer
----@param client_id integer
+---@param bufnr (integer) Buffer number, or `0` for current buffer
+---@param client_id (integer) The ID of the |vim.lsp.Client|
 function M.stop(bufnr, client_id)
   vim.validate({
     bufnr = { bufnr, 'n', false },
     client_id = { client_id, 'n', false },
   })
 
+  if bufnr == 0 then
+    bufnr = api.nvim_get_current_buf()
+  end
+
   local highlighter = STHighlighter.active[bufnr]
   if not highlighter then
     return
@@ -741,12 +749,15 @@ end
 --- mark will be deleted by the semantic token engine when appropriate; for
 --- example, when the LSP sends updated tokens. This function is intended for
 --- use inside |LspTokenUpdate| callbacks.
----@param token (table) a semantic token, found as `args.data.token` in |LspTokenUpdate|.
----@param bufnr (integer) the buffer to highlight
+---@param token (table) A semantic token, found as `args.data.token` in |LspTokenUpdate|
+---@param bufnr (integer) The buffer to highlight, or `0` for current buffer
 ---@param client_id (integer) The ID of the |vim.lsp.Client|
 ---@param hl_group (string) Highlight group name
 ---@param opts? vim.lsp.semantic_tokens.highlight_token.Opts  Optional parameters:
 function M.highlight_token(token, bufnr, client_id, hl_group, opts)
+  if bufnr == 0 then
+    bufnr = api.nvim_get_current_buf()
+  end
   local highlighter = STHighlighter.active[bufnr]
   if not highlighter then
     return
diff --git a/test/functional/plugin/lsp/semantic_tokens_spec.lua b/test/functional/plugin/lsp/semantic_tokens_spec.lua
index 013393095e..60f02b0521 100644
--- a/test/functional/plugin/lsp/semantic_tokens_spec.lua
+++ b/test/functional/plugin/lsp/semantic_tokens_spec.lua
@@ -273,6 +273,63 @@ describe('semantic token highlighting', function()
       end
     )
 
+    it('highlights start and stop when using "0" for current buffer', function()
+      exec_lua([[
+        bufnr = vim.api.nvim_get_current_buf()
+        vim.api.nvim_win_set_buf(0, bufnr)
+        client_id = vim.lsp.start({ name = 'dummy', cmd = server.cmd })
+      ]])
+
+      insert(text)
+
+      exec_lua([[
+        vim.notify = function() end
+        vim.lsp.semantic_tokens.stop(0, client_id)
+      ]])
+
+      screen:expect {
+        grid = [[
+        #include <iostream>                     |
+                                                |
+        int main()                              |
+        {                                       |
+            int x;                              |
+        #ifdef __cplusplus                      |
+            std::cout << x << "\n";             |
+        #else                                   |
+            printf("%d\n", x);                  |
+        #endif                                  |
+        }                                       |
+        ^}                                       |
+        {1:~                                       }|*3
+                                                |
+      ]],
+      }
+
+      exec_lua([[
+        vim.lsp.semantic_tokens.start(0, client_id)
+      ]])
+
+      screen:expect {
+        grid = [[
+        #include <iostream>                     |
+                                                |
+        int {8:main}()                              |
+        {                                       |
+            int {7:x};                              |
+        #ifdef {5:__cplusplus}                      |
+            {4:std}::{2:cout} << {2:x} << "\n";             |
+        {6:#else}                                   |
+        {6:    printf("%d\n", x);}                  |
+        {6:#endif}                                  |
+        }                                       |
+        ^}                                       |
+        {1:~                                       }|*3
+                                                |
+      ]],
+      }
+    end)
+
     it('buffer is re-highlighted when force refreshed', function()
       exec_lua([[
         bufnr = vim.api.nvim_get_current_buf()