docs(lua): more improvements (#24387)

* docs(lua): teach lua2dox how to table * docs(lua): teach gen_vimdoc.py about local functions No more need to mark local functions with @private * docs(lua): mention @nodoc and @meta in dev-lua-doc * fixup! Co-authored-by: Justin M. Keyes <justinkz@gmail.com> --------- Co-authored-by: Justin M. Keyes <justinkz@gmail.com>
2025-10-26 12:27:24 +00:00 · 2023-07-18 15:42:30 +01:00
parent d0ae529861
commit be74807eef
39 changed files with 322 additions and 511 deletions
--- a/runtime/lua/vim/lsp/_watchfiles.lua
+++ b/runtime/lua/vim/lsp/_watchfiles.lua
@@ -5,7 +5,6 @@ local lpeg = vim.lpeg

 local M = {}

---@private
 --- Parses the raw pattern into an |lpeg| pattern. LPeg patterns natively support the "this" or "that"
 --- alternative constructions described in the LSP spec that cannot be expressed in a standard Lua pattern.
 ---
--- a/runtime/lua/vim/lsp/buf.lua
+++ b/runtime/lua/vim/lsp/buf.lua
@@ -5,7 +5,6 @@ local npcall = vim.F.npcall

 local M = {}

---@private
 --- Sends an async request to all active clients attached to the current
 --- buffer.
 ---
@@ -45,7 +44,6 @@ function M.hover()
  request('textDocument/hover', params)
 end

---@private
 local function request_with_options(name, params, options)
  local req_handler
  if options then
@@ -120,7 +118,6 @@ function M.completion(context)
  return request('textDocument/completion', params)
 end

---@private
 ---@param bufnr integer
 ---@param mode "v"|"V"
 ---@return table {start={row,col}, end={row,col}} using (1, 0) indexing
@@ -218,7 +215,6 @@ function M.format(options)
    vim.notify('[LSP] Format request failed, no matching language servers.')
  end

-  ---@private
  local function set_range(client, params)
    if range then
      local range_params =
@@ -289,7 +285,6 @@ function M.rename(new_name, options)
  -- Compute early to account for cursor movements after going async
  local cword = vim.fn.expand('<cword>')

-  ---@private
  local function get_text_at_range(range, offset_encoding)
    return api.nvim_buf_get_text(
      bufnr,
@@ -307,7 +302,6 @@ function M.rename(new_name, options)
      return
    end

-    ---@private
    local function rename(name)
      local params = util.make_position_params(win, client.offset_encoding)
      params.newName = name
@@ -408,7 +402,6 @@ function M.document_symbol(options)
  request_with_options('textDocument/documentSymbol', params, options)
 end

---@private
 local function pick_call_hierarchy_item(call_hierarchy_items)
  if not call_hierarchy_items then
    return
@@ -428,7 +421,6 @@ local function pick_call_hierarchy_item(call_hierarchy_items)
  return choice
 end

---@private
 local function call_hierarchy(method)
  local params = util.make_position_params()
  request('textDocument/prepareCallHierarchy', params, function(err, result, ctx)
@@ -579,8 +571,6 @@ function M.clear_references()
  util.buf_clear_references()
 end

---@private
--
 --- This is not public because the main extension point is
 --- vim.ui.select which can be overridden independently.
 ---
@@ -592,7 +582,6 @@ end
 local function on_code_action_results(results, ctx, options)
  local action_tuples = {}

-  ---@private
  local function action_filter(a)
    -- filter by specified action kind
    if options and options.context and options.context.only then
@@ -632,7 +621,6 @@ local function on_code_action_results(results, ctx, options)
    return
  end

-  ---@private
  local function apply_action(action, client)
    if action.edit then
      util.apply_workspace_edit(action.edit, client.offset_encoding)
@@ -643,7 +631,6 @@ local function on_code_action_results(results, ctx, options)
    end
  end

-  ---@private
  local function on_user_choice(action_tuple)
    if not action_tuple then
      return
@@ -701,7 +688,6 @@ end

 --- Requests code actions from all clients and calls the handler exactly once
 --- with all aggregated results
---@private
 local function code_action_request(params, options)
  local bufnr = api.nvim_get_current_buf()
  local method = 'textDocument/codeAction'
--- a/runtime/lua/vim/lsp/codelens.lua
+++ b/runtime/lua/vim/lsp/codelens.lua
@@ -26,7 +26,6 @@ local namespaces = setmetatable({}, {
 ---@private
 M.__namespaces = namespaces

---@private
 local function execute_lens(lens, bufnr, client_id)
  local line = lens.range.start.line
  api.nvim_buf_clear_namespace(bufnr, namespaces[client_id], line, line + 1)
@@ -89,7 +88,6 @@ function M.run()
  end
 end

---@private
 local function resolve_bufnr(bufnr)
  return bufnr == 0 and api.nvim_get_current_buf() or bufnr
 end
@@ -186,7 +184,6 @@ function M.save(lenses, bufnr, client_id)
  lenses_by_client[client_id] = lenses
 end

---@private
 local function resolve_lenses(lenses, bufnr, client_id, callback)
  lenses = lenses or {}
  local num_lens = vim.tbl_count(lenses)
@@ -195,7 +192,6 @@ local function resolve_lenses(lenses, bufnr, client_id, callback)
    return
  end

-  ---@private
  local function countdown()
    num_lens = num_lens - 1
    if num_lens == 0 then
--- a/runtime/lua/vim/lsp/diagnostic.lua
+++ b/runtime/lua/vim/lsp/diagnostic.lua
@@ -5,7 +5,7 @@ local protocol = require('vim.lsp.protocol')
 local M = {}

 local DEFAULT_CLIENT_ID = -1
---@private
+
 local function get_client_id(client_id)
  if client_id == nil then
    client_id = DEFAULT_CLIENT_ID
@@ -14,7 +14,6 @@ local function get_client_id(client_id)
  return client_id
 end

---@private
 ---@param severity lsp.DiagnosticSeverity
 local function severity_lsp_to_vim(severity)
  if type(severity) == 'string' then
@@ -23,7 +22,6 @@ local function severity_lsp_to_vim(severity)
  return severity
 end

---@private
 ---@return lsp.DiagnosticSeverity
 local function severity_vim_to_lsp(severity)
  if type(severity) == 'string' then
@@ -32,7 +30,6 @@ local function severity_vim_to_lsp(severity)
  return severity
 end

---@private
 ---@return integer
 local function line_byte_from_position(lines, lnum, col, offset_encoding)
  if not lines or offset_encoding == 'utf-8' then
@@ -48,7 +45,6 @@ local function line_byte_from_position(lines, lnum, col, offset_encoding)
  return col
 end

---@private
 local function get_buf_lines(bufnr)
  if vim.api.nvim_buf_is_loaded(bufnr) then
    return vim.api.nvim_buf_get_lines(bufnr, 0, -1, false)
@@ -73,7 +69,6 @@ local function get_buf_lines(bufnr)
  return lines
 end

--- @private
 --- @param diagnostic lsp.Diagnostic
 --- @param client_id integer
 --- @return table?
@@ -96,7 +91,6 @@ local function tags_lsp_to_vim(diagnostic, client_id)
  return tags
 end

---@private
 ---@param diagnostics lsp.Diagnostic[]
 ---@param bufnr integer
 ---@param client_id integer
@@ -133,7 +127,6 @@ local function diagnostic_lsp_to_vim(diagnostics, bufnr, client_id)
  end, diagnostics)
 end

--- @private
 --- @param diagnostics Diagnostic[]
 --- @return lsp.Diagnostic[]
 local function diagnostic_vim_to_lsp(diagnostics)
--- a/runtime/lua/vim/lsp/handlers.lua
+++ b/runtime/lua/vim/lsp/handlers.lua
@@ -7,7 +7,6 @@ local M = {}

 -- FIXME: DOC: Expose in vimdocs

---@private
 --- Writes to error buffer.
 ---@param ... string Will be concatenated before being written
 local function err_message(...)
@@ -246,7 +245,6 @@ M['textDocument/references'] = function(_, result, ctx, config)
  end
 end

---@private
 --- Return a function that converts LSP responses to list items and opens the list
 ---
 --- The returned function has an optional {config} parameter that accepts a table
@@ -380,7 +378,6 @@ end
 --see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
 M['textDocument/hover'] = M.hover

---@private
 --- Jumps to a location. Used as a handler for multiple LSP methods.
 ---@param _ nil not used
 ---@param result (table) result of LSP method; a location or a list of locations.
--- a/runtime/lua/vim/lsp/inlay_hint.lua
+++ b/runtime/lua/vim/lsp/inlay_hint.lua
@@ -17,7 +17,6 @@ local namespace = api.nvim_create_namespace('vim_lsp_inlayhint')
 local augroup = api.nvim_create_augroup('vim_lsp_inlayhint', {})

 --- Reset the request debounce timer of a buffer
---@private
 local function reset_timer(reset_bufnr)
  local timer = bufstates[reset_bufnr].timer
  if timer then
@@ -63,7 +62,6 @@ function M.on_inlayhint(err, result, ctx, _)
  end

  local lines = api.nvim_buf_get_lines(bufnr, 0, -1, false)
-  ---@private
  local function pos_to_byte(position)
    local col = position.character
    if col > 0 then
@@ -89,7 +87,6 @@ function M.on_inlayhint(err, result, ctx, _)
  api.nvim__buf_redraw_range(bufnr, 0, -1)
 end

---@private
 local function resolve_bufnr(bufnr)
  return bufnr > 0 and bufnr or api.nvim_get_current_buf()
 end
@@ -100,7 +97,6 @@ end
 ---  - bufnr (integer, default: 0): Buffer whose hints to refresh
 ---  - only_visible (boolean, default: false): Whether to only refresh hints for the visible regions of the buffer
 ---
---@private
 local function refresh(opts)
  opts = opts or {}
  local bufnr = resolve_bufnr(opts.bufnr or 0)
@@ -159,7 +155,6 @@ end

 --- Clear inlay hints
 ---@param bufnr (integer) Buffer handle, or 0 for current
---@private
 local function clear(bufnr)
  bufnr = resolve_bufnr(bufnr)
  if not bufstates[bufnr] then
@@ -178,7 +173,6 @@ local function clear(bufnr)
  api.nvim__buf_redraw_range(bufnr, 0, -1)
 end

---@private
 local function make_request(request_bufnr)
  reset_timer(request_bufnr)
  refresh({ bufnr = request_bufnr })
@@ -186,7 +180,6 @@ end

 --- Enable inlay hints for a buffer
 ---@param bufnr (integer) Buffer handle, or 0 for current
---@private
 local function enable(bufnr)
  bufnr = resolve_bufnr(bufnr)
  local bufstate = bufstates[bufnr]
@@ -228,7 +221,6 @@ end

 --- Disable inlay hints for a buffer
 ---@param bufnr (integer) Buffer handle, or 0 for current
---@private
 local function disable(bufnr)
  bufnr = resolve_bufnr(bufnr)
  if bufstates[bufnr] and bufstates[bufnr].enabled then
@@ -240,7 +232,6 @@ end

 --- Toggle inlay hints for a buffer
 ---@param bufnr (integer) Buffer handle, or 0 for current
---@private
 local function toggle(bufnr)
  bufnr = resolve_bufnr(bufnr)
  local bufstate = bufstates[bufnr]
--- a/runtime/lua/vim/lsp/log.lua
+++ b/runtime/lua/vim/lsp/log.lua
@@ -2,14 +2,12 @@

 local log = {}

-- FIXME: DOC
-- Should be exposed in the vim docs.
--
-- Log level dictionary with reverse lookup as well.
--
-- Can be used to lookup the number from the name or the name from the number.
-- Levels by name: "TRACE", "DEBUG", "INFO", "WARN", "ERROR", "OFF"
-- Level numbers begin with "TRACE" at 0
+--- Log level dictionary with reverse lookup as well.
+---
+--- Can be used to lookup the number from the name or the name from the number.
+--- Levels by name: "TRACE", "DEBUG", "INFO", "WARN", "ERROR", "OFF"
+--- Level numbers begin with "TRACE" at 0
+--- @nodoc
 log.levels = vim.deepcopy(vim.log.levels)

 -- Default log level is warn.
@@ -20,7 +18,6 @@ local format_func = function(arg)
 end

 do
-  ---@private
  local function notify(msg, level)
    if vim.in_fast_event() then
      vim.schedule(function()
@@ -32,7 +29,6 @@ do
  end

  local path_sep = vim.uv.os_uname().version:match('Windows') and '\\' or '/'
-  ---@private
  local function path_join(...)
    return table.concat(vim.tbl_flatten({ ... }), path_sep)
  end
@@ -50,7 +46,6 @@ do
  end

  local logfile, openerr
-  ---@private
  --- Opens log file. Returns true if file is open, false on error
  local function open_logfile()
    -- Try to open file only once
--- a/runtime/lua/vim/lsp/rpc.lua
+++ b/runtime/lua/vim/lsp/rpc.lua
@@ -5,7 +5,6 @@ local validate, schedule, schedule_wrap = vim.validate, vim.schedule, vim.schedu

 local is_win = uv.os_uname().version:find('Windows')

---@private
 --- Checks whether a given path exists and is a directory.
 ---@param filename (string) path to check
 ---@return boolean
@@ -14,7 +13,6 @@ local function is_dir(filename)
  return stat and stat.type == 'directory' or false
 end

---@private
 --- Embeds the given string into a table and correctly computes `Content-Length`.
 ---
 ---@param encoded_message (string)
@@ -28,7 +26,6 @@ local function format_message_with_content_length(encoded_message)
  })
 end

---@private
 --- Parses an LSP Message's header
 ---
 ---@param header string: The header to parse.
@@ -60,7 +57,6 @@ local header_start_pattern = ('content'):gsub('%w', function(c)
  return '[' .. c .. c:upper() .. ']'
 end)

---@private
 --- The actual workhorse.
 local function request_parser_loop()
  local buffer = '' -- only for header part
@@ -115,8 +111,11 @@ local function request_parser_loop()
  end
 end

+local M = {}
+
 --- Mapping of error codes used by the client
-local client_errors = {
+--- @nodoc
+M.client_errors = {
  INVALID_SERVER_MESSAGE = 1,
  INVALID_SERVER_JSON = 2,
  NO_RESULT_CALLBACK_FOUND = 3,
@@ -126,13 +125,13 @@ local client_errors = {
  SERVER_RESULT_CALLBACK_ERROR = 7,
 }

-client_errors = vim.tbl_add_reverse_lookup(client_errors)
+M.client_errors = vim.tbl_add_reverse_lookup(M.client_errors)

 --- Constructs an error message from an LSP error object.
 ---
 ---@param err (table) The error object
 ---@returns (string) The formatted error message
-local function format_rpc_error(err)
+function M.format_rpc_error(err)
  validate({
    err = { err, 't' },
  })
@@ -163,7 +162,7 @@ end
 ---@param code integer RPC error code defined in `vim.lsp.protocol.ErrorCodes`
 ---@param message string|nil arbitrary message to send to server
 ---@param data any|nil arbitrary data to send to server
-local function rpc_response_error(code, message, data)
+function M.rpc_response_error(code, message, data)
  -- TODO should this error or just pick a sane error (like InternalError)?
  local code_name = assert(protocol.ErrorCodes[code], 'Invalid RPC error code')
  return setmetatable({
@@ -171,7 +170,7 @@ local function rpc_response_error(code, message, data)
    message = message or code_name,
    data = data,
  }, {
-    __tostring = format_rpc_error,
+    __tostring = M.format_rpc_error,
  })
 end

@@ -185,6 +184,7 @@ local default_dispatchers = {}
 function default_dispatchers.notification(method, params)
  local _ = log.debug() and log.debug('notification', method, params)
 end
+
 ---@private
 --- Default dispatcher for requests sent to an LSP server.
 ---
@@ -194,8 +194,9 @@ end
 ---@return table `vim.lsp.protocol.ErrorCodes.MethodNotFound`
 function default_dispatchers.server_request(method, params)
  local _ = log.debug() and log.debug('server_request', method, params)
-  return nil, rpc_response_error(protocol.ErrorCodes.MethodNotFound)
+  return nil, M.rpc_response_error(protocol.ErrorCodes.MethodNotFound)
 end
+
 ---@private
 --- Default dispatcher for when a client exits.
 ---
@@ -205,6 +206,7 @@ end
 function default_dispatchers.on_exit(code, signal)
  local _ = log.info() and log.info('client_exit', { code = code, signal = signal })
 end
+
 ---@private
 --- Default dispatcher for client errors.
 ---
@@ -212,11 +214,11 @@ end
 ---@param err (any): Details about the error
 ---any)
 function default_dispatchers.on_error(code, err)
-  local _ = log.error() and log.error('client_error:', client_errors[code], err)
+  local _ = log.error() and log.error('client_error:', M.client_errors[code], err)
 end

 ---@private
-local function create_read_loop(handle_body, on_no_chunk, on_error)
+function M.create_read_loop(handle_body, on_no_chunk, on_error)
  local parse_chunk = coroutine.wrap(request_parser_loop)
  parse_chunk()
  return function(err, chunk)
@@ -329,7 +331,7 @@ end

 ---@private
 function Client:on_error(errkind, ...)
-  assert(client_errors[errkind])
+  assert(M.client_errors[errkind])
  -- TODO what to do if this fails?
  pcall(self.dispatchers.on_error, errkind, ...)
 end
@@ -356,7 +358,7 @@ end
 function Client:handle_body(body)
  local ok, decoded = pcall(vim.json.decode, body, { luanil = { object = true } })
  if not ok then
-    self:on_error(client_errors.INVALID_SERVER_JSON, decoded)
+    self:on_error(M.client_errors.INVALID_SERVER_JSON, decoded)
    return
  end
  local _ = log.debug() and log.debug('rpc.receive', decoded)
@@ -369,7 +371,7 @@ function Client:handle_body(body)
      coroutine.wrap(function()
        local status, result
        status, result, err = self:try_call(
-          client_errors.SERVER_REQUEST_HANDLER_ERROR,
+          M.client_errors.SERVER_REQUEST_HANDLER_ERROR,
          self.dispatchers.server_request,
          decoded.method,
          decoded.params
@@ -401,7 +403,7 @@ function Client:handle_body(body)
          end
        else
          -- On an exception, result will contain the error message.
-          err = rpc_response_error(protocol.ErrorCodes.InternalError, result)
+          err = M.rpc_response_error(protocol.ErrorCodes.InternalError, result)
          result = nil
        end
        self:send_response(decoded.id, err, result)
@@ -454,34 +456,33 @@ function Client:handle_body(body)
      })
      if decoded.error then
        decoded.error = setmetatable(decoded.error, {
-          __tostring = format_rpc_error,
+          __tostring = M.format_rpc_error,
        })
      end
      self:try_call(
-        client_errors.SERVER_RESULT_CALLBACK_ERROR,
+        M.client_errors.SERVER_RESULT_CALLBACK_ERROR,
        callback,
        decoded.error,
        decoded.result
      )
    else
-      self:on_error(client_errors.NO_RESULT_CALLBACK_FOUND, decoded)
+      self:on_error(M.client_errors.NO_RESULT_CALLBACK_FOUND, decoded)
      local _ = log.error() and log.error('No callback found for server response id ' .. result_id)
    end
  elseif type(decoded.method) == 'string' then
    -- Notification
    self:try_call(
-      client_errors.NOTIFICATION_HANDLER_ERROR,
+      M.client_errors.NOTIFICATION_HANDLER_ERROR,
      self.dispatchers.notification,
      decoded.method,
      decoded.params
    )
  else
    -- Invalid server message
-    self:on_error(client_errors.INVALID_SERVER_MESSAGE, decoded)
+    self:on_error(M.client_errors.INVALID_SERVER_MESSAGE, decoded)
  end
 end

---@private
 ---@return RpcClient
 local function new_client(dispatchers, transport)
  local state = {
@@ -494,7 +495,6 @@ local function new_client(dispatchers, transport)
  return setmetatable(state, { __index = Client })
 end

---@private
 ---@param client RpcClient
 local function public_client(client)
  local result = {}
@@ -531,7 +531,6 @@ local function public_client(client)
  return result
 end

---@private
 local function merge_dispatchers(dispatchers)
  if dispatchers then
    local user_dispatchers = dispatchers
@@ -565,7 +564,7 @@ end
 ---@param host string
 ---@param port integer
 ---@return function
-local function connect(host, port)
+function M.connect(host, port)
  return function(dispatchers)
    dispatchers = merge_dispatchers(dispatchers)
    local tcp = uv.new_tcp()
@@ -600,8 +599,8 @@ local function connect(host, port)
      local handle_body = function(body)
        client:handle_body(body)
      end
-      tcp:read_start(create_read_loop(handle_body, transport.terminate, function(read_err)
-        client:on_error(client_errors.READ_ERROR, read_err)
+      tcp:read_start(M.create_read_loop(handle_body, transport.terminate, function(read_err)
+        client:on_error(M.client_errors.READ_ERROR, read_err)
      end))
    end)

@@ -630,7 +629,7 @@ end
 --- - `request()` |vim.lsp.rpc.request()|
 --- - `is_closing()` returns a boolean indicating if the RPC is closing.
 --- - `terminate()` terminates the RPC client.
-local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
+function M.start(cmd, cmd_args, dispatchers, extra_spawn_params)
  if log.info() then
    log.info('Starting RPC client', { cmd = cmd, args = cmd_args, extra = extra_spawn_params })
  end
@@ -667,8 +666,8 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
    client:handle_body(body)
  end

-  local stdout_handler = create_read_loop(handle_body, nil, function(err)
-    client:on_error(client_errors.READ_ERROR, err)
+  local stdout_handler = M.create_read_loop(handle_body, nil, function(err)
+    client:on_error(M.client_errors.READ_ERROR, err)
  end)

  local stderr_handler = function(_, chunk)
@@ -714,11 +713,4 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
  return public_client(client)
 end

-return {
-  start = start,
-  connect = connect,
-  rpc_response_error = rpc_response_error,
-  format_rpc_error = format_rpc_error,
-  client_errors = client_errors,
-  create_read_loop = create_read_loop,
-}
+return M
--- a/runtime/lua/vim/lsp/semantic_tokens.lua
+++ b/runtime/lua/vim/lsp/semantic_tokens.lua
@@ -41,8 +41,6 @@ local STHighlighter = { active = {} }
 ---
 --- Return the index i in range such that tokens[j].line < line for all j < i, and
 --- tokens[j].line >= line for all j >= i, or return hi if no such index is found.
---
---@private
 local function lower_bound(tokens, line, lo, hi)
  while lo < hi do
    local mid = bit.rshift(lo + hi, 1) -- Equivalent to floor((lo + hi) / 2).
@@ -59,8 +57,6 @@ end
 ---
 --- Return the index i in range such that tokens[j].line <= line for all j < i, and
 --- tokens[j].line > line for all j >= i, or return hi if no such index is found.
---
---@private
 local function upper_bound(tokens, line, lo, hi)
  while lo < hi do
    local mid = bit.rshift(lo + hi, 1) -- Equivalent to floor((lo + hi) / 2).
@@ -75,7 +71,6 @@ end

 --- Extracts modifier strings from the encoded number in the token array
 ---
---@private
 ---@return table<string, boolean>
 local function modifiers_from_number(x, modifiers_table)
  local modifiers = {}
@@ -93,7 +88,6 @@ end

 --- Converts a raw token list to a list of highlight ranges used by the on_win callback
 ---
---@private
 ---@return STTokenRange[]
 local function tokens_to_ranges(data, bufnr, client, request)
  local legend = client.server_capabilities.semanticTokensProvider.legend
@@ -137,7 +131,6 @@ local function tokens_to_ranges(data, bufnr, client, request)
    local token_type = token_types[data[i + 3] + 1]
    local modifiers = modifiers_from_number(data[i + 4], token_modifiers)

-    ---@private
    local function _get_byte_pos(col)
      if col > 0 then
        local buf_line = lines[line + 1] or ''
--- a/runtime/lua/vim/lsp/sync.lua
+++ b/runtime/lua/vim/lsp/sync.lua
@@ -48,7 +48,6 @@ local str_utfindex = vim.str_utfindex
 local str_utf_start = vim.str_utf_start
 local str_utf_end = vim.str_utf_end

---@private
 -- Given a line, byte idx, and offset_encoding convert to the
 -- utf-8, utf-16, or utf-32 index.
 ---@param line string the line to index into
@@ -74,7 +73,6 @@ local function byte_to_utf(line, byte, offset_encoding)
  return utf_idx + 1
 end

---@private
 local function compute_line_length(line, offset_encoding)
  local length
  local _
@@ -88,7 +86,6 @@ local function compute_line_length(line, offset_encoding)
  return length
 end

---@private
 -- Given a line, byte idx, alignment, and offset_encoding convert to the aligned
 -- utf-8 index and either the utf-16, or utf-32 index.
 ---@param line string the line to index into
@@ -122,7 +119,6 @@ local function align_end_position(line, byte, offset_encoding)
  return byte, char
 end

---@private
 --- Finds the first line, byte, and char index of the difference between the previous and current lines buffer normalized to the previous codepoint.
 ---@param prev_lines table list of lines from previous buffer
 ---@param curr_lines table list of lines from current buffer
@@ -198,7 +194,6 @@ local function compute_start_range(
  return { line_idx = firstline, byte_idx = byte_idx, char_idx = char_idx }
 end

---@private
 --- Finds the last line and byte index of the differences between prev and current buffer.
 --- Normalized to the next codepoint.
 --- prev_end_range is the text range sent to the server representing the changed region.
@@ -307,7 +302,6 @@ local function compute_end_range(
  return prev_end_range, curr_end_range
 end

---@private
 --- Get the text of the range defined by start and end line/column
 ---@param lines table list of lines
 ---@param start_range table table returned by first_difference
@@ -343,7 +337,6 @@ local function extract_text(lines, start_range, end_range, line_ending)
  end
 end

---@private
 -- rangelength depends on the offset encoding
 -- bytes for utf-8 (clangd with extension)
 -- codepoints for utf-16
--- a/runtime/lua/vim/lsp/tagfunc.lua
+++ b/runtime/lua/vim/lsp/tagfunc.lua
@@ -1,7 +1,6 @@
 local lsp = vim.lsp
 local util = lsp.util

---@private
 local function mk_tag_item(name, range, uri, offset_encoding)
  local bufnr = vim.uri_to_bufnr(uri)
  -- This is get_line_byte_from_position is 0-indexed, call cursor expects a 1-indexed position
@@ -13,7 +12,6 @@ local function mk_tag_item(name, range, uri, offset_encoding)
  }
 end

---@private
 local function query_definition(pattern)
  local params = util.make_position_params()
  local results_by_client, err = lsp.buf_request_sync(0, 'textDocument/definition', params, 1000)
@@ -42,7 +40,6 @@ local function query_definition(pattern)
  return results
 end

---@private
 local function query_workspace_symbols(pattern)
  local results_by_client, err =
    lsp.buf_request_sync(0, 'workspace/symbol', { query = pattern }, 1000)
@@ -62,7 +59,6 @@ local function query_workspace_symbols(pattern)
  return results
 end

---@private
 local function tagfunc(pattern, flags)
  local matches
  if string.match(flags, 'c') then
--- a/runtime/lua/vim/lsp/util.lua
+++ b/runtime/lua/vim/lsp/util.lua
@@ -22,7 +22,6 @@ local default_border = {
  { ' ', 'NormalFloat' },
 }

---@private
 --- Check the border given by opts or the default border for the additional
 --- size it adds to a float.
 ---@param opts table optional options for the floating window
@@ -60,7 +59,6 @@ local function get_border_size(opts)
        )
      )
    end
-    ---@private
    local function border_width(id)
      id = (id - 1) % #border + 1
      if type(border[id]) == 'table' then
@@ -77,7 +75,6 @@ local function get_border_size(opts)
        )
      )
    end
-    ---@private
    local function border_height(id)
      id = (id - 1) % #border + 1
      if type(border[id]) == 'table' then
@@ -103,13 +100,11 @@ local function get_border_size(opts)
  return { height = height, width = width }
 end

---@private
 local function split_lines(value)
  value = string.gsub(value, '\r\n?', '\n')
  return split(value, '\n', { plain = true })
 end

---@private
 local function create_window_without_focus()
  local prev = vim.api.nvim_get_current_win()
  vim.cmd.new()
@@ -219,7 +214,6 @@ function M.set_lines(lines, A, B, new_lines)
  return lines
 end

---@private
 local function sort_by_key(fn)
  return function(a, b)
    local ka, kb = fn(a), fn(b)
@@ -234,7 +228,6 @@ local function sort_by_key(fn)
  end
 end

---@private
 --- Gets the zero-indexed lines from the given buffer.
 --- Works on unloaded buffers by reading the file using libuv to bypass buf reading events.
 --- Falls back to loading the buffer and nvim_buf_get_lines for buffers with non-file URI.
@@ -250,7 +243,6 @@ local function get_lines(bufnr, rows)
    bufnr = api.nvim_get_current_buf()
  end

-  ---@private
  local function buf_lines()
    local lines = {}
    for _, row in ipairs(rows) do
@@ -316,7 +308,6 @@ local function get_lines(bufnr, rows)
  return lines
 end

---@private
 --- Gets the zero-indexed line from the given buffer.
 --- Works on unloaded buffers by reading the file using libuv to bypass buf reading events.
 --- Falls back to loading the buffer and nvim_buf_get_lines for buffers with non-file URI.
@@ -328,7 +319,6 @@ local function get_line(bufnr, row)
  return get_lines(bufnr, { row })[row]
 end

---@private
 --- Position is a https://microsoft.github.io/language-server-protocol/specifications/specification-current/#position
 --- Returns a zero-indexed column, since set_lines() does the conversion to
 ---@param offset_encoding string|nil utf-8|utf-16|utf-32
@@ -670,7 +660,6 @@ function M.parse_snippet(input)
  return parsed
 end

---@private
 --- Sorts by CompletionItem.sortText.
 ---
 --see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_completion
@@ -680,7 +669,6 @@ local function sort_completion_items(items)
  end)
 end

---@private
 --- Returns text that should be inserted when selecting completion item. The
 --- precedence is as follows: textEdit.newText > insertText > label
 --see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_completion
@@ -703,7 +691,6 @@ local function get_completion_word(item)
  return item.label
 end

---@private
 --- Some language servers return complementary candidates whose prefixes do not
 --- match are also returned. So we exclude completion candidates whose prefix
 --- does not match.
@@ -784,7 +771,6 @@ function M.text_document_completion_list_to_complete_items(result, prefix)
  return matches
 end

---@private
 --- Like vim.fn.bufwinid except it works across tabpages.
 local function bufwinid(bufnr)
  for _, win in ipairs(api.nvim_list_wins()) do
@@ -795,7 +781,6 @@ local function bufwinid(bufnr)
 end

 --- Get list of buffers for a directory
---@private
 local function get_dir_bufs(path)
  path = path:gsub('([^%w])', '%%%1')
  local buffers = {}
@@ -855,7 +840,6 @@ function M.rename(old_fname, new_fname, opts)
  end
 end

---@private
 local function create_file(change)
  local opts = change.options or {}
  -- from spec: Overwrite wins over `ignoreIfExists`
@@ -870,7 +854,6 @@ local function create_file(change)
  vim.fn.bufadd(fname)
 end

---@private
 local function delete_file(change)
  local opts = change.options or {}
  local fname = vim.uri_to_fname(change.uri)
@@ -1266,7 +1249,6 @@ function M.preview_location(location, opts)
  return M.open_floating_preview(contents, syntax, opts)
 end

---@private
 local function find_window_by_var(name, value)
  for _, win in ipairs(api.nvim_list_wins()) do
    if npcall(api.nvim_win_get_var, win, name) == value then
@@ -1305,7 +1287,6 @@ end
 --- Generates a table mapping markdown code block lang to vim syntax,
 --- based on g:markdown_fenced_languages
 ---@return table table of lang -> syntax mappings
---@private
 local function get_markdown_fences()
  local fences = {}
  for _, fence in pairs(vim.g.markdown_fenced_languages or {}) do
@@ -1460,7 +1441,6 @@ function M.stylize_markdown(bufnr, contents, opts)
  api.nvim_buf_set_lines(bufnr, 0, -1, false, stripped)

  local idx = 1
-  ---@private
  -- keep track of syntaxes we already included.
  -- no need to include the same syntax more than once
  local langs = {}
@@ -1521,7 +1501,6 @@ function M.stylize_markdown(bufnr, contents, opts)
  return stripped
 end

---@private
 --- Closes the preview window
 ---
 ---@param winnr integer window id of preview window
@@ -1539,7 +1518,6 @@ local function close_preview_window(winnr, bufnrs)
  end)
 end

---@private
 --- Creates autocommands to close a preview window when events happen.
 ---
 ---@param events table list of events
@@ -1905,7 +1883,6 @@ end
 ---
 ---@param symbols table DocumentSymbol[] or SymbolInformation[]
 function M.symbols_to_items(symbols, bufnr)
-  ---@private
  local function _symbols_to_items(_symbols, _items, _bufnr)
    for _, symbol in ipairs(_symbols) do
      if symbol.location then -- SymbolInformation type
@@ -1991,7 +1968,6 @@ function M.try_trim_markdown_code_blocks(lines)
  return 'markdown'
 end

---@private
 ---@param window integer|nil: window handle or 0 for current, defaults to current
 ---@param offset_encoding string utf-8|utf-16|utf-32|nil defaults to `offset_encoding` of first client of buffer of `window`
 local function make_position_param(window, offset_encoding)
@@ -2209,6 +2185,7 @@ end

 M._get_line_byte_from_position = get_line_byte_from_position

+---@nodoc
 M.buf_versions = {}

 return M