docs(lsp): add annotations for private functions

runtime/doc/lsp.txt

@@ -575,9 +575,6 @@ buf_request_sync({bufnr}, {method}, {params}, {timeout_ms})
                     error, returns `(nil, err)` where `err` is a string
                     describing the failure reason.
 
-check_clients_closed()                        *vim.lsp.check_clients_closed()*
-                TODO: Documentation
-
 client()                                                      *vim.lsp.client*
                 LSP client object. You can get an active client object via
                 |vim.lsp.get_client_by_id()| or
@@ -650,12 +647,21 @@ client_is_stopped({client_id})                   *vim.lsp.client_is_stopped()*
                 Return: ~
                     true if client is stopped, false otherwise.
 
-flush({client})                                              *vim.lsp.flush()*
-                TODO: Documentation
-
                                             *vim.lsp.for_each_buffer_client()*
 for_each_buffer_client({bufnr}, {fn})
-                TODO: Documentation
+                Invokes a function for each LSP client attached to a buffer.
+
+                Parameters: ~
+                    {bufnr}  number Buffer number
+                    {fn}     function Function to run on each client attached
+                             to buffer {bufnr}. The function takes the client,
+                             client ID, and buffer number as arguments.
+                             Example: >
+
+                               vim.lsp.for_each_buffer_client(0, function(client, client_id, bufnr)
+                                 print(vim.inspect(client))
+                               end)
+<
 
 formatexpr({opts})                                      *vim.lsp.formatexpr()*
                 Provides an interface between the built-in client and a
@@ -721,16 +727,6 @@ omnifunc({findstart}, {base})                             *vim.lsp.omnifunc()*
                     |complete-items|
                     |CompleteDone|
 
-                                                           *vim.lsp.prepare()*
-prepare({bufnr}, {firstline}, {lastline}, {new_lastline})
-                TODO: Documentation
-
-reset({client_id})                                           *vim.lsp.reset()*
-                TODO: Documentation
-
-reset_buf({client}, {bufnr})                             *vim.lsp.reset_buf()*
-                TODO: Documentation
-
 set_log_level({level})                               *vim.lsp.set_log_level()*
                 Sets the global log level for LSP logging.
 
@@ -1097,9 +1093,6 @@ outgoing_calls()                                *vim.lsp.buf.outgoing_calls()*
                 cursor in the |quickfix| window. If the symbol can resolve to
                 multiple items, the user can pick one in the |inputlist|.
 
-prepare_rename({err}, {result})                 *vim.lsp.buf.prepare_rename()*
-                TODO: Documentation
-
                                              *vim.lsp.buf.range_code_action()*
 range_code_action({context}, {start_pos}, {end_pos})
                 Performs |vim.lsp.buf.code_action()| for a given range.
@@ -1370,9 +1363,6 @@ buf_highlight_references({bufnr}, {references}, {offset_encoding})
                 See also: ~
                     https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#documentHighlight
 
-buf_lines()                                         *vim.lsp.util.buf_lines()*
-                TODO: Documentation
-
                                              *vim.lsp.util.character_offset()*
 character_offset({bufnr}, {row}, {col})
                 Returns the UTF-32 and UTF-16 offsets for a position in a
@@ -1439,12 +1429,6 @@ convert_signature_help_to_markdown_lines({signature_help}, {ft}, {triggers})
                 See also: ~
                     https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp
 
-create_file({change})                             *vim.lsp.util.create_file()*
-                TODO: Documentation
-
-delete_file({change})                             *vim.lsp.util.delete_file()*
-                TODO: Documentation
-
                                      *vim.lsp.util.extract_completion_items()*
 extract_completion_items({result})
                 Can be used to extract the completion items from a `textDocument/completion` request, which may return one of `CompletionItem[]` , `CompletionList` or null.
@@ -1472,9 +1456,6 @@ get_effective_tabstop({bufnr})          *vim.lsp.util.get_effective_tabstop()*
                 See also: ~
                     |softtabstop|
 
-get_progress_messages()                 *vim.lsp.util.get_progress_messages()*
-                TODO: Documentation
-
 jump_to_location({location})                 *vim.lsp.util.jump_to_location()*
                 Jumps to a location.
 
@@ -1771,7 +1752,10 @@ get_filename()                                    *vim.lsp.log.get_filename()*
                     (string) log filename
 
 get_level()                                          *vim.lsp.log.get_level()*
-                TODO: Documentation
+                Gets the current log level.
+
+                Return: ~
+                    string current log level
 
 set_format_func({handle})                      *vim.lsp.log.set_format_func()*
                 Sets formatting function used to format logs
@@ -1910,10 +1894,6 @@ compute_diff({prev_lines}, {curr_lines}, {firstline}, {lastline},
                 Return: ~
                     table TextDocumentContentChangeEvent see https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#textDocumentContentChangeEvent
 
-                                          *vim.lsp.sync.compute_line_length()*
-compute_line_length({line}, {offset_encoding})
-                TODO: Documentation
-
 
 ==============================================================================
 Lua module: vim.lsp.protocol                                    *lsp-protocol*

runtime/doc/lua.txt

@@ -1190,9 +1190,6 @@ defer_fn({fn}, {timeout})                                     *vim.defer_fn()*
                 Return: ~
                     timer luv timer object
 
-insert_keys({obj})                                         *vim.insert_keys()*
-                TODO: Documentation
-
 inspect({object}, {options})                                   *vim.inspect()*
                 Return a human-readable representation of the given object.
 
@@ -1365,9 +1362,6 @@ is_callable({f})                                           *vim.is_callable()*
                 Return: ~
                     true if `f` is callable, else false
 
-is_valid({opt})                                               *vim.is_valid()*
-                TODO: Documentation
-
 list_extend({dst}, {src}, {start}, {finish})               *vim.list_extend()*
                 Extends a list-like table with the values of another list-like
                 table.

runtime/lua/vim/lsp.lua

@@ -137,12 +137,6 @@ local all_buffer_active_clients = {}
 local uninitialized_clients = {}
 
 ---@private
---- Invokes a function for each LSP client attached to the buffer {bufnr}.
----
----@param bufnr (Number) of buffer
----@param fn (function({client}, {client_id}, {bufnr}) Function to run on
----each client attached to that buffer.
----@param restrict_client_ids table list of client ids on which to restrict function application.
 local function for_each_buffer_client(bufnr, fn, restrict_client_ids)
   validate {
     fn = { fn, 'f' };
@@ -327,6 +321,7 @@ do
   ---     timer?: uv_timer
   local state_by_client = {}
 
+  ---@private
   function changetracking.init(client, bufnr)
     local state = state_by_client[client.id]
     if not state then
@@ -348,6 +343,7 @@ do
     state.buffers[bufnr] = nvim_buf_get_lines(bufnr, 0, -1, true)
   end
 
+  ---@private
   function changetracking.reset_buf(client, bufnr)
     changetracking.flush(client)
     local state = state_by_client[client.id]
@@ -356,6 +352,7 @@ do
     end
   end
 
+  ---@private
   function changetracking.reset(client_id)
     local state = state_by_client[client_id]
     if state then
@@ -364,6 +361,7 @@ do
     end
   end
 
+  ---@private
   function changetracking.prepare(bufnr, firstline, lastline, new_lastline)
     local incremental_changes = function(client)
       local cached_buffers = state_by_client[client.id].buffers
@@ -447,6 +445,7 @@ do
   end
 
   --- Flushes any outstanding change notification.
+  ---@private
   function changetracking.flush(client)
     local state = state_by_client[client.id]
     if state then
@@ -1297,6 +1296,7 @@ function lsp._vim_exit_handler()
 
   local poll_time = 50
 
+  ---@private
   local function check_clients_closed()
     for client_id, timeout in pairs(timeouts) do
       timeouts[client_id] = timeout - poll_time
@@ -1683,7 +1683,17 @@ function lsp.get_log_path()
   return log.get_filename()
 end
 
---- Call {fn} for every client attached to {bufnr}
+--- Invokes a function for each LSP client attached to a buffer.
+---
+---@param bufnr number Buffer number
+---@param fn function Function to run on each client attached to buffer
+---                   {bufnr}. The function takes the client, client ID, and
+---                   buffer number as arguments. Example:
+---             <pre>
+---               vim.lsp.for_each_buffer_client(0, function(client, client_id, bufnr)
+---                 print(vim.inspect(client))
+---               end)
+---             </pre>
 function lsp.for_each_buffer_client(bufnr, fn)
   return for_each_buffer_client(bufnr, fn)
 end

runtime/lua/vim/lsp/buf.lua

@@ -263,6 +263,7 @@ function M.rename(new_name)
     request('textDocument/rename', params)
   end
 
+  ---@private
   local function prepare_rename(err, result)
     if err == nil and result == nil then
       vim.notify('nothing to rename', vim.log.levels.INFO)

runtime/lua/vim/lsp/log.lua

@@ -101,6 +101,7 @@ function log.set_level(level)
 end
 
 --- Gets the current log level.
+---@return string current log level
 function log.get_level()
   return current_log_level
 end

runtime/lua/vim/lsp/sync.lua

@@ -74,6 +74,7 @@ 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 _

runtime/lua/vim/lsp/util.lua

@@ -158,6 +158,7 @@ end
 local function get_lines(bufnr, rows)
   rows = type(rows) == "table" and rows or { rows }
 
+  ---@private
   local function buf_lines()
     local lines = {}
     for _, row in pairs(rows) do
@@ -262,6 +263,7 @@ local function get_line_byte_from_position(bufnr, position, offset_encoding)
 end
 
 --- Process and return progress reports from lsp server
+---@private
 function M.get_progress_messages()
 
   local new_messages = {}
@@ -657,7 +659,7 @@ function M.rename(old_fname, new_fname, opts)
   api.nvim_buf_delete(oldbuf, { force = true })
 end
 
-
+---@private
 local function create_file(change)
   local opts = change.options or {}
   -- from spec: Overwrite wins over `ignoreIfExists`
@@ -669,7 +671,7 @@ 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)

runtime/lua/vim/shared.lua

@@ -559,6 +559,7 @@ do
     return type(val) == t or (t == 'callable' and vim.is_callable(val))
   end
 
+  ---@private
   local function is_valid(opt)
     if type(opt) ~= 'table' then
       return false, string.format('opt: expected table, got %s', type(opt))

src/nvim/lua/vim.lua

@@ -580,6 +580,7 @@ function vim._expand_pat(pat, env)
   end
 
   local keys = {}
+  ---@private
   local function insert_keys(obj)
     for k,_ in pairs(obj) do
       if type(k) == "string" and string.sub(k,1,string.len(match_part)) == match_part then