diff options
39 files changed, 328 insertions, 517 deletions
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index db878ac304..f36ef1df0a 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -233,6 +233,8 @@ Docstring format: - List-items start with `-` (useful to nest or "indent") - Use `<pre>` for code samples. Code samples can be annotated as `vim` or `lua` +- Use `@nodoc` to prevent documentation generation. +- Files which has `@meta` are only used for typing and documentation. Example: the help for |vim.paste()| is generated from a docstring decorating vim.paste in runtime/lua/vim/_editor.lua like this: > diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index fa109dbc26..edc9f50c8d 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -758,6 +758,24 @@ client_is_stopped({client_id}) *vim.lsp.client_is_stopped()* Return: ~ (boolean) stopped true if client is stopped, false otherwise. +commands *vim.lsp.commands* + Registry for client side commands. This is an extension point for plugins + to handle custom commands which are not part of the core language server + protocol specification. + + The registry is a table where the key is a unique command name, and the + value is a function which is called if any LSP action (code action, code + lenses, ...) triggers the command. + + If a LSP response contains a command for which no matching entry is + available in this registry, the command will be executed via the LSP + server using `workspace/executeCommand`. + + The first argument to the function will be the `Command`: Command title: + String command: String arguments?: any[] + + The second argument is the `ctx` of |lsp-handler| + formatexpr({opts}) *vim.lsp.formatexpr()* Provides an interface between the built-in client and a `formatexpr` function. diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index ac40d61e20..0b894897d1 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -591,16 +591,6 @@ If you want to exclude visual selections from highlighting on yank, use: >vim au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false} < -vim.highlight.priorities *vim.highlight.priorities* - - Table with default priorities used for highlighting: - • `syntax`: `50`, used for standard syntax highlighting - • `treesitter`: `100`, used for tree-sitter-based highlighting - • `semantic_tokens`: `125`, used for LSP semantic token highlighting - • `diagnostics`: `150`, used for code analysis such as diagnostics - • `user`: `200`, used for user-triggered highlights such as LSP document - symbols or `on_yank` autocommands - vim.highlight.on_yank({opts}) *vim.highlight.on_yank()* Highlight the yanked text @@ -616,6 +606,15 @@ vim.highlight.on_yank({opts}) *vim.highlight.on_yank()* • priority integer priority (default |vim.highlight.priorities|`.user`) +vim.highlight.priorities *vim.highlight.priorities* + Table with default priorities used for highlighting: + • `syntax`: `50`, used for standard syntax highlighting + • `treesitter`: `100`, used for tree-sitter-based highlighting + • `semantic_tokens`: `125`, used for LSP semantic token highlighting + • `diagnostics`: `150`, used for code analysis such as diagnostics + • `user`: `200`, used for user-triggered highlights such as LSP document + symbols or `on_yank` autocommands + *vim.highlight.range()* vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {opts}) Apply highlight group to range of text. @@ -1189,15 +1188,6 @@ vim.v *vim.v* |v:| variables. Invalid or unset key returns `nil`. -vim.env *vim.env* - Environment variables defined in the editor session. - See |expand-env| and |:let-environment| for the Vimscript behavior. - Invalid or unset key returns `nil`. - Example: >lua - vim.env.FOO = 'bar' - print(vim.env.TERM) -< - ` ` *lua-options* *lua-vim-options* *lua-vim-set* @@ -1221,62 +1211,6 @@ window-scoped options. Note that this must NOT be confused with |local-options| and |:setlocal|. There is also |vim.go| that only accesses the global value of a |global-local| option, see |:setglobal|. -vim.o *vim.o* - Get or set |options|. Like `:set`. Invalid key is an error. - - Note: this works on both buffer-scoped and window-scoped options using the - current buffer and window. - - Example: >lua - vim.o.cmdheight = 4 - print(vim.o.columns) - print(vim.o.foo) -- error: invalid key -< - -vim.go *vim.go* - Get or set global |options|. Like `:setglobal`. Invalid key is - an error. - - Note: this is different from |vim.o| because this accesses the global - option value and thus is mostly useful for use with |global-local| - options. - - Example: >lua - vim.go.cmdheight = 4 - print(vim.go.columns) - print(vim.go.bar) -- error: invalid key -< - -vim.bo[{bufnr}] *vim.bo* - Get or set buffer-scoped |options| for the buffer with number {bufnr}. - Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current - buffer is used. Invalid {bufnr} or key is an error. - - Note: this is equivalent to both `:set` and `:setlocal`. - - Example: >lua - local bufnr = vim.api.nvim_get_current_buf() - vim.bo[bufnr].buflisted = true -- same as vim.bo.buflisted = true - print(vim.bo.comments) - print(vim.bo.baz) -- error: invalid key - -vim.wo[{winid}][{bufnr}] *vim.wo* - Get or set window-scoped |options| for the window with handle {winid} and - buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like - `:set` otherwise. If [{winid}] is omitted then the current window is - used. Invalid {winid}, {bufnr} or key is an error. - - Note: only {bufnr} with value `0` (the current buffer in the window) is - supported. - - Example: >lua - local winid = vim.api.nvim_get_current_win() - vim.wo[winid].number = true -- same as vim.wo.number = true - print(vim.wo.foldmarker) - print(vim.wo.quux) -- error: invalid key - vim.wo[winid][0].spell = false -- like ':setlocal nospell' -< - ` ` *vim.opt_local* *vim.opt_global* *vim.opt* @@ -1419,11 +1353,81 @@ Option:remove({value}) *vim.opt:remove()* Parameters: ~ • {value} (string) Value to remove +vim.bo *vim.bo* + Get or set buffer-scoped |options| for the buffer with number {bufnr}. + Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current + buffer is used. Invalid {bufnr} or key is an error. + + Note: this is equivalent to both `:set` and `:setlocal`. + + Example: >lua + local bufnr = vim.api.nvim_get_current_buf() + vim.bo[bufnr].buflisted = true -- same as vim.bo.buflisted = true + print(vim.bo.comments) + print(vim.bo.baz) -- error: invalid key +< + + Parameters: ~ + • {bufnr} (integer|nil) + +vim.env *vim.env* + Environment variables defined in the editor session. See |expand-env| and + |:let-environment| for the Vimscript behavior. Invalid or unset key + returns `nil` . Example: >lua + vim.env.FOO = 'bar' + print(vim.env.TERM) +< + + Parameters: ~ + • {var} (string) + +vim.go *vim.go* + Get or set global |options|. Like `:setglobal`. Invalid key is an error. + + Note: this is different from |vim.o| because this accesses the global + option value and thus is mostly useful for use with |global-local| + options. + + Example: >lua + vim.go.cmdheight = 4 + print(vim.go.columns) + print(vim.go.bar) -- error: invalid key +< + +vim.o *vim.o* + Get or set |options|. Like `:set`. Invalid key is an error. + + Note: this works on both buffer-scoped and window-scoped options using the + current buffer and window. + + Example: >lua + vim.o.cmdheight = 4 + print(vim.o.columns) + print(vim.o.foo) -- error: invalid key +< + +vim.wo *vim.wo* + Get or set window-scoped |options| for the window with handle {winid} and + buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like + `:set` otherwise. If [{winid}] is omitted then the current window is used. + Invalid {winid}, {bufnr} or key is an error. + + Note: only {bufnr} with value `0` (the current buffer in the window) is + supported. + + Example: >lua + local winid = vim.api.nvim_get_current_win() + vim.wo[winid].number = true -- same as vim.wo.number = true + print(vim.wo.foldmarker) + print(vim.wo.quux) -- error: invalid key + vim.wo[winid][0].spell = false -- like ':setlocal nospell' +< + ============================================================================== Lua module: vim *lua-vim* -vim.cmd({command}) *vim.cmd()* +vim.cmd *vim.cmd()* Execute Vim script commands. Note that `vim.cmd` can be indexed with a command name to return a @@ -1468,10 +1472,6 @@ vim.cmd({command}) *vim.cmd()* See also: ~ • |ex-cmd-index| - *vim.connection_failure_errmsg()* -vim.connection_failure_errmsg({consequence}) - TODO: Documentation - vim.defer_fn({fn}, {timeout}) *vim.defer_fn()* Defers calling {fn} until {timeout} ms passes. @@ -1501,7 +1501,7 @@ vim.deprecate({name}, {alternative}, {version}, {plugin}, {backtrace}) Return: ~ (string|nil) # Deprecated message, or nil if no message was shown. -vim.inspect({object}, {options}) *vim.inspect()* +vim.inspect *vim.inspect()* Gets a human-readable representation of the given object. See also: ~ diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua index bb0aa97a0d..4372aef7b3 100644 --- a/runtime/lua/vim/_editor.lua +++ b/runtime/lua/vim/_editor.lua @@ -54,6 +54,7 @@ vim._extra = { inspect_pos = true, } +--- @private vim.log = { levels = { TRACE = 0, @@ -187,9 +188,7 @@ end ---@see |vim.print()| ---@see https://github.com/kikito/inspect.lua ---@see https://github.com/mpeterv/vinspect -local function inspect(object, options) -- luacheck: no unused - error(object, options) -- Stub for gen_vimdoc.py -end +vim.inspect = vim.inspect do local tdots, tick, got_line1, undo_started, trailing_nl = 0, 0, false, false, false @@ -328,6 +327,7 @@ function vim.schedule_wrap(cb) end -- vim.fn.{func}(...) +---@private vim.fn = setmetatable({}, { __index = function(t, key) local _fn @@ -345,10 +345,13 @@ vim.fn = setmetatable({}, { end, }) +--- @private vim.funcref = function(viml_func_name) return vim.fn[viml_func_name] end +local VIM_CMD_ARG_MAX = 20 + --- Execute Vim script commands. --- --- Note that `vim.cmd` can be indexed with a command name to return a callable function to the @@ -389,12 +392,6 @@ end --- If a table, executes a single command. In this case, it is an alias --- to |nvim_cmd()| where `opts` is empty. ---@see |ex-cmd-index| -function vim.cmd(command) -- luacheck: no unused - error(command) -- Stub for gen_vimdoc.py -end - -local VIM_CMD_ARG_MAX = 20 - vim.cmd = setmetatable({}, { __call = function(_, command) if type(command) == 'table' then @@ -435,7 +432,6 @@ vim.cmd = setmetatable({}, { do local validate = vim.validate - ---@private local function make_dict_accessor(scope, handle) validate({ scope = { scope, 's' }, @@ -745,7 +741,6 @@ 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 @@ -1008,7 +1003,6 @@ end function vim._init_default_mappings() -- mappings - ---@private local function region_chunks(region) local chunks = {} local maxcol = vim.v.maxcol @@ -1020,7 +1014,6 @@ function vim._init_default_mappings() return chunks end - ---@private local function _visual_search(cmd) assert(cmd == '/' or cmd == '?') vim.api.nvim_feedkeys('\27', 'nx', true) -- Escape visual mode. @@ -1037,7 +1030,6 @@ function vim._init_default_mappings() vim.api.nvim_feedkeys(search_cmd, 'nx', true) end - ---@private local function map(mode, lhs, rhs) vim.keymap.set(mode, lhs, rhs, { desc = 'Nvim builtin' }) end diff --git a/runtime/lua/vim/_inspector.lua b/runtime/lua/vim/_inspector.lua index ecd39c35bc..3f7b9d2c23 100644 --- a/runtime/lua/vim/_inspector.lua +++ b/runtime/lua/vim/_inspector.lua @@ -56,7 +56,6 @@ function vim.inspect_pos(bufnr, row, col, filter) } -- resolve hl links - ---@private local function resolve_hl(data) if data.hl_group then local hlid = vim.api.nvim_get_hl_id_by_name(data.hl_group) @@ -91,7 +90,6 @@ function vim.inspect_pos(bufnr, row, col, filter) end --- Convert an extmark tuple into a table - --- @private local function to_map(extmark) extmark = { id = extmark[1], @@ -107,7 +105,6 @@ function vim.inspect_pos(bufnr, row, col, filter) end --- Check if an extmark overlaps this position - --- @private local function is_here(extmark) return (row >= extmark.row and row <= extmark.end_row) -- within the rows of the extmark and (row > extmark.row or col >= extmark.col) -- either not the first row, or in range of the col @@ -148,17 +145,14 @@ function vim.show_pos(bufnr, row, col, filter) local lines = { {} } - ---@private local function append(str, hl) table.insert(lines[#lines], { str, hl }) end - ---@private local function nl() table.insert(lines, {}) end - ---@private local function item(data, comment) append(' - ') append(data.hl_group, data.hl_group) diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua index 6dbe4cf64a..d54e8b447c 100644 --- a/runtime/lua/vim/_options.lua +++ b/runtime/lua/vim/_options.lua @@ -92,15 +92,6 @@ ---vim.v *vim.v* --- |v:| variables. --- Invalid or unset key returns `nil`. ---- ----vim.env *vim.env* ---- Environment variables defined in the editor session. ---- See |expand-env| and |:let-environment| for the Vimscript behavior. ---- Invalid or unset key returns `nil`. ---- Example: >lua ---- vim.env.FOO = 'bar' ---- print(vim.env.TERM) ----< ---</pre> local api = vim.api @@ -118,7 +109,6 @@ local key_value_options = { --- Convert a vimoption_T style dictionary to the correct OptionType associated with it. ---@return string ----@private local function get_option_metatype(name, info) if info.type == 'string' then if info.flaglist then @@ -143,6 +133,14 @@ local options_info = setmetatable({}, { end, }) +---Environment variables defined in the editor session. +---See |expand-env| and |:let-environment| for the Vimscript behavior. +---Invalid or unset key returns `nil`. +---Example: <pre>lua +--- vim.env.FOO = 'bar' +--- print(vim.env.TERM) +---</pre> +---@param var string vim.env = setmetatable({}, { __index = function(_, k) local v = vim.fn.getenv(k) @@ -157,7 +155,6 @@ vim.env = setmetatable({}, { end, }) ----@private local function opt_validate(option_name, target_scope) local scope = options_info[option_name].scope if scope ~= target_scope then @@ -174,7 +171,6 @@ local function opt_validate(option_name, target_scope) end end ----@private local function new_buf_opt_accessor(bufnr) return setmetatable({}, { __index = function(_, k) @@ -192,7 +188,6 @@ local function new_buf_opt_accessor(bufnr) }) end ----@private local function new_win_opt_accessor(winid, bufnr) return setmetatable({}, { __index = function(_, k) @@ -253,19 +248,15 @@ end ---global value of a |global-local| option, see |:setglobal|. ---</pre> ----@addtogroup lua-vimscript ----@brief <pre>help ----vim.o *vim.o* ---- Get or set |options|. Like `:set`. Invalid key is an error. +---Get or set |options|. Like `:set`. Invalid key is an error. --- ---- Note: this works on both buffer-scoped and window-scoped options using the ---- current buffer and window. +---Note: this works on both buffer-scoped and window-scoped options using the +---current buffer and window. --- ---- Example: >lua ---- vim.o.cmdheight = 4 ---- print(vim.o.columns) ---- print(vim.o.foo) -- error: invalid key ----< +---Example: <pre>lua +--- vim.o.cmdheight = 4 +--- print(vim.o.columns) +--- print(vim.o.foo) -- error: invalid key ---</pre> vim.o = setmetatable({}, { __index = function(_, k) @@ -276,21 +267,17 @@ vim.o = setmetatable({}, { end, }) ----@addtogroup lua-vimscript ----@brief <pre>help ----vim.go *vim.go* ---- Get or set global |options|. Like `:setglobal`. Invalid key is ---- an error. ---- ---- Note: this is different from |vim.o| because this accesses the global ---- option value and thus is mostly useful for use with |global-local| ---- options. ---- ---- Example: >lua ---- vim.go.cmdheight = 4 ---- print(vim.go.columns) ---- print(vim.go.bar) -- error: invalid key ----< +---Get or set global |options|. Like `:setglobal`. Invalid key is +---an error. +--- +---Note: this is different from |vim.o| because this accesses the global +---option value and thus is mostly useful for use with |global-local| +---options. +--- +---Example: <pre>lua +--- vim.go.cmdheight = 4 +--- print(vim.go.columns) +--- print(vim.go.bar) -- error: invalid key ---</pre> vim.go = setmetatable({}, { __index = function(_, k) @@ -301,41 +288,36 @@ vim.go = setmetatable({}, { end, }) ----@addtogroup lua-vimscript ----@brief <pre>help ----vim.bo[{bufnr}] *vim.bo* ---- Get or set buffer-scoped |options| for the buffer with number {bufnr}. ---- Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current ---- buffer is used. Invalid {bufnr} or key is an error. ---- ---- Note: this is equivalent to both `:set` and `:setlocal`. ---- ---- Example: >lua ---- local bufnr = vim.api.nvim_get_current_buf() ---- vim.bo[bufnr].buflisted = true -- same as vim.bo.buflisted = true ---- print(vim.bo.comments) ---- print(vim.bo.baz) -- error: invalid key +---Get or set buffer-scoped |options| for the buffer with number {bufnr}. +---Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current +---buffer is used. Invalid {bufnr} or key is an error. +--- +---Note: this is equivalent to both `:set` and `:setlocal`. +--- +---Example: <pre>lua +--- local bufnr = vim.api.nvim_get_current_buf() +--- vim.bo[bufnr].buflisted = true -- same as vim.bo.buflisted = true +--- print(vim.bo.comments) +--- print(vim.bo.baz) -- error: invalid key ---</pre> +---@param bufnr integer|nil vim.bo = new_buf_opt_accessor() ----@addtogroup lua-vimscript ----@brief <pre>help ----vim.wo[{winid}][{bufnr}] *vim.wo* ---- Get or set window-scoped |options| for the window with handle {winid} and ---- buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like ---- `:set` otherwise. If [{winid}] is omitted then the current window is ---- used. Invalid {winid}, {bufnr} or key is an error. ---- ---- Note: only {bufnr} with value `0` (the current buffer in the window) is ---- supported. ---- ---- Example: >lua ---- local winid = vim.api.nvim_get_current_win() ---- vim.wo[winid].number = true -- same as vim.wo.number = true ---- print(vim.wo.foldmarker) ---- print(vim.wo.quux) -- error: invalid key ---- vim.wo[winid][0].spell = false -- like ':setlocal nospell' ----< +---Get or set window-scoped |options| for the window with handle {winid} and +---buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like +---`:set` otherwise. If [{winid}] is omitted then the current window is +---used. Invalid {winid}, {bufnr} or key is an error. +--- +---Note: only {bufnr} with value `0` (the current buffer in the window) is +---supported. +--- +---Example: <pre>lua +--- local winid = vim.api.nvim_get_current_win() +--- vim.wo[winid].number = true -- same as vim.wo.number = true +--- print(vim.wo.foldmarker) +--- print(vim.wo.quux) -- error: invalid key +--- vim.wo[winid][0].spell = false -- like ':setlocal nospell' +--- ---</pre> vim.wo = new_win_opt_accessor() @@ -348,7 +330,6 @@ vim.wo = new_win_opt_accessor() ---@brief ]] --- Preserves the order and does not mutate the original list ---- @private local function remove_duplicate_values(t) local result, seen = {}, {} for _, v in ipairs(t) do @@ -364,7 +345,6 @@ end -- Check whether the OptionTypes is allowed for vim.opt -- If it does not match, throw an error which indicates which option causes the error. ---- @private local function assert_valid_value(name, value, types) local type_of_value = type(value) for _, valid_type in ipairs(types) do @@ -383,17 +363,14 @@ local function assert_valid_value(name, value, types) ) end ---- @private local function passthrough(_, x) return x end ---- @private local function tbl_merge(left, right) return vim.tbl_extend('force', left, right) end ---- @private local function tbl_remove(t, value) if type(value) == 'string' then t[value] = nil @@ -475,7 +452,6 @@ local to_vim_value = { } --- Convert a Lua value to a vimoption_T value ---- @private local function convert_value_to_vim(name, info, value) if value == nil then return vim.NIL @@ -591,7 +567,6 @@ local to_lua_value = { } --- Converts a vimoption_T style value to a Lua value ---- @private local function convert_value_to_lua(info, option_value) return to_lua_value[info.metatype](info, option_value) end @@ -618,7 +593,6 @@ local prepend_methods = { } --- Handles the '^' operator ---- @private local function prepend_value(info, current, new) return prepend_methods[info.metatype]( convert_value_to_lua(info, current), @@ -648,7 +622,6 @@ local add_methods = { } --- Handles the '+' operator ---- @private local function add_value(info, current, new) return add_methods[info.metatype]( convert_value_to_lua(info, current), @@ -656,7 +629,6 @@ local function add_value(info, current, new) ) end ---- @private local function remove_one_item(t, val) if vim.tbl_islist(t) then local remove_index = nil @@ -700,16 +672,13 @@ local remove_methods = { } --- Handles the '-' operator ---- @private local function remove_value(info, current, new) return remove_methods[info.metatype](convert_value_to_lua(info, current), new) end ---- @private local function create_option_accessor(scope) local option_mt - --- @private local function make_option(name, value) local info = assert(options_info[name], 'Not a valid option name: ' .. name) @@ -923,6 +892,11 @@ function Option:prepend(value) end -- luacheck: no unused ---@diagnostic disable-next-line:unused-local used for gen_vimdoc function Option:remove(value) end -- luacheck: no unused +---@private vim.opt = create_option_accessor() + +---@private vim.opt_local = create_option_accessor('local') + +---@private vim.opt_global = create_option_accessor('global') diff --git a/runtime/lua/vim/_system.lua b/runtime/lua/vim/_system.lua index ff566866c0..e6dab90425 100644 --- a/runtime/lua/vim/_system.lua +++ b/runtime/lua/vim/_system.lua @@ -30,7 +30,6 @@ local uv = vim.uv --- @field cmd string[] --- @field result? SystemCompleted ----@private ---@param state SystemState local function close_handles(state) for _, handle in pairs({ state.handle, state.stdin, state.stdout, state.stderr }) do @@ -128,7 +127,6 @@ function SystemObj:is_closing() return handle == nil or handle:is_closing() end ----@private ---@param output function|'false' ---@return uv_stream_t? ---@return function? Handler @@ -145,7 +143,6 @@ local function setup_output(output) return nil, nil end ----@private ---@param input string|string[]|true|nil ---@return uv_stream_t? ---@return string|string[]? diff --git a/runtime/lua/vim/_watch.lua b/runtime/lua/vim/_watch.lua index 00b7416098..dc5f59f38b 100644 --- a/runtime/lua/vim/_watch.lua +++ b/runtime/lua/vim/_watch.lua @@ -7,7 +7,6 @@ M.FileChangeType = vim.tbl_add_reverse_lookup({ Deleted = 3, }) ----@private --- Joins filepath elements by static '/' separator --- ---@param ... (string) The path elements. @@ -16,7 +15,6 @@ local function filepath_join(...) return table.concat({ ... }, '/') end ----@private --- Stops and closes a libuv |uv_fs_event_t| or |uv_fs_poll_t| handle --- ---@param handle (uv_fs_event_t|uv_fs_poll_t) The handle to stop @@ -88,7 +86,6 @@ local default_poll_interval_ms = 2000 --- @field include_pattern? userdata --- @field exclude_pattern? userdata ----@private --- Implementation for poll, hiding internally-used parameters. --- ---@param path string diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua index 093bfb631e..f0adc4104e 100644 --- a/runtime/lua/vim/diagnostic.lua +++ b/runtime/lua/vim/diagnostic.lua @@ -72,7 +72,6 @@ local bufs_waiting_to_update = setmetatable({}, bufnr_and_namespace_cacher_mt) local all_namespaces = {} ----@private local function to_severity(severity) if type(severity) == 'string' then return assert( @@ -83,7 +82,6 @@ local function to_severity(severity) return severity end ----@private local function filter_by_severity(severity, diagnostics) if not severity then return diagnostics @@ -104,7 +102,6 @@ local function filter_by_severity(severity, diagnostics) end, diagnostics) end ----@private local function count_sources(bufnr) local seen = {} local count = 0 @@ -119,7 +116,6 @@ local function count_sources(bufnr) return count end ----@private local function prefix_source(diagnostics) return vim.tbl_map(function(d) if not d.source then @@ -132,7 +128,6 @@ local function prefix_source(diagnostics) end, diagnostics) end ----@private local function reformat_diagnostics(format, diagnostics) vim.validate({ format = { format, 'f' }, @@ -146,7 +141,6 @@ local function reformat_diagnostics(format, diagnostics) return formatted end ----@private local function enabled_value(option, namespace) local ns = namespace and M.get_namespace(namespace) or {} if ns.opts and type(ns.opts[option]) == 'table' then @@ -160,7 +154,6 @@ local function enabled_value(option, namespace) return {} end ----@private local function resolve_optional_value(option, value, namespace, bufnr) if not value then return false @@ -180,7 +173,6 @@ local function resolve_optional_value(option, value, namespace, bufnr) end end ----@private local function get_resolved_options(opts, namespace, bufnr) local ns = namespace and M.get_namespace(namespace) or {} -- Do not use tbl_deep_extend so that an empty table can be used to reset to default values @@ -202,7 +194,6 @@ local diagnostic_severities = { } -- Make a map from DiagnosticSeverity -> Highlight Name ----@private local function make_highlight_map(base_name) local result = {} for k in pairs(diagnostic_severities) do @@ -243,7 +234,6 @@ local define_default_signs = (function() end end)() ----@private local function get_bufnr(bufnr) if not bufnr or bufnr == 0 then return api.nvim_get_current_buf() @@ -251,7 +241,6 @@ local function get_bufnr(bufnr) return bufnr end ----@private local function diagnostic_lines(diagnostics) if not diagnostics then return {} @@ -269,7 +258,6 @@ local function diagnostic_lines(diagnostics) return diagnostics_by_line end ----@private local function set_diagnostic_cache(namespace, bufnr, diagnostics) for _, diagnostic in ipairs(diagnostics) do assert(diagnostic.lnum, 'Diagnostic line number is required') @@ -284,7 +272,6 @@ local function set_diagnostic_cache(namespace, bufnr, diagnostics) diagnostic_cache[bufnr][namespace] = diagnostics end ----@private local function restore_extmarks(bufnr, last) for ns, extmarks in pairs(diagnostic_cache_extmarks[bufnr]) do local extmarks_current = api.nvim_buf_get_extmarks(bufnr, ns, 0, -1, { details = true }) @@ -306,7 +293,6 @@ local function restore_extmarks(bufnr, last) end end ----@private local function save_extmarks(namespace, bufnr) bufnr = get_bufnr(bufnr) if not diagnostic_attached_buffers[bufnr] then @@ -326,13 +312,11 @@ end local registered_autocmds = {} ----@private local function make_augroup_key(namespace, bufnr) local ns = M.get_namespace(namespace) return string.format('DiagnosticInsertLeave:%s:%s', bufnr, ns.name) end ----@private local function execute_scheduled_display(namespace, bufnr) local args = bufs_waiting_to_update[bufnr][namespace] if not args then @@ -348,7 +332,6 @@ end --- Table of autocmd events to fire the update for displaying new diagnostic information local insert_leave_auto_cmds = { 'InsertLeave', 'CursorHoldI' } ----@private local function schedule_display(namespace, bufnr, args) bufs_waiting_to_update[bufnr][namespace] = args @@ -367,7 +350,6 @@ local function schedule_display(namespace, bufnr, args) end end ----@private local function clear_scheduled_display(namespace, bufnr) local key = make_augroup_key(namespace, bufnr) @@ -377,7 +359,6 @@ local function clear_scheduled_display(namespace, bufnr) end end ----@private local function get_diagnostics(bufnr, opts, clamp) opts = opts or {} @@ -392,7 +373,6 @@ local function get_diagnostics(bufnr, opts, clamp) end, }) - ---@private local function add(b, d) if not opts.lnum or d.lnum == opts.lnum then if clamp and api.nvim_buf_is_loaded(b) then @@ -416,7 +396,6 @@ local function get_diagnostics(bufnr, opts, clamp) end end - ---@private local function add_all_diags(buf, diags) for _, diagnostic in pairs(diags) do add(buf, diagnostic) @@ -450,7 +429,6 @@ local function get_diagnostics(bufnr, opts, clamp) return diagnostics end ----@private local function set_list(loclist, opts) opts = opts or {} local open = vim.F.if_nil(opts.open, true) @@ -474,7 +452,6 @@ local function set_list(loclist, opts) end end ----@private local function next_diagnostic(position, search_forward, bufnr, opts, namespace) position[1] = position[1] - 1 bufnr = get_bufnr(bufnr) @@ -525,7 +502,6 @@ local function next_diagnostic(position, search_forward, bufnr, opts, namespace) end end ----@private local function diagnostic_move_pos(opts, pos) opts = opts or {} diff --git a/runtime/lua/vim/filetype.lua b/runtime/lua/vim/filetype.lua index 33d451315d..40f72a217d 100644 --- a/runtime/lua/vim/filetype.lua +++ b/runtime/lua/vim/filetype.lua @@ -2,7 +2,6 @@ local api = vim.api local M = {} ----@private local function starsetf(ft, opts) return { function(path, bufnr) @@ -2317,7 +2316,6 @@ local pattern = { -- luacheck: pop -- luacheck: pop ----@private local function sort_by_priority(t) local sorted = {} for k, v in pairs(t) do @@ -2341,7 +2339,6 @@ end local pattern_sorted = sort_by_priority(pattern) ----@private local function normalize_path(path, as_pattern) local normal = path:gsub('\\', '/') if normal:find('^~') then @@ -2456,7 +2453,6 @@ function M.add(filetypes) end end ----@private local function dispatch(ft, path, bufnr, ...) local on_detect if type(ft) == 'function' then @@ -2483,7 +2479,6 @@ end -- Lookup table/cache for patterns that contain an environment variable pattern, e.g. ${SOME_VAR}. local expand_env_lookup = {} ----@private local function match_pattern(name, path, tail, pat) if expand_env_lookup[pat] == nil then expand_env_lookup[pat] = pat:find('%${') ~= nil diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua index d06dcb87cf..842767098c 100644 --- a/runtime/lua/vim/fs.lua +++ b/runtime/lua/vim/fs.lua @@ -218,7 +218,6 @@ function M.find(names, opts) local matches = {} - ---@private local function add(match) matches[#matches + 1] = M.normalize(match) if #matches == limit then diff --git a/runtime/lua/vim/highlight.lua b/runtime/lua/vim/highlight.lua index 0eb782339c..14b0e71312 100644 --- a/runtime/lua/vim/highlight.lua +++ b/runtime/lua/vim/highlight.lua @@ -18,23 +18,18 @@ ---<pre>vim --- au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false} ---</pre> ---- ---- <pre>help ----vim.highlight.priorities *vim.highlight.priorities* ---- ---- Table with default priorities used for highlighting: ---- • `syntax`: `50`, used for standard syntax highlighting ---- • `treesitter`: `100`, used for tree-sitter-based highlighting ---- • `semantic_tokens`: `125`, used for LSP semantic token highlighting ---- • `diagnostics`: `150`, used for code analysis such as diagnostics ---- • `user`: `200`, used for user-triggered highlights such as LSP document ---- symbols or `on_yank` autocommands ----</pre> local api = vim.api local M = {} +--- Table with default priorities used for highlighting: +--- - `syntax`: `50`, used for standard syntax highlighting +--- - `treesitter`: `100`, used for tree-sitter-based highlighting +--- - `semantic_tokens`: `125`, used for LSP semantic token highlighting +--- - `diagnostics`: `150`, used for code analysis such as diagnostics +--- - `user`: `200`, used for user-triggered highlights such as LSP document +--- symbols or `on_yank` autocommands M.priorities = { syntax = 50, treesitter = 100, diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua index 6c1afcad91..7bffcc9c20 100644 --- a/runtime/lua/vim/iter.lua +++ b/runtime/lua/vim/iter.lua @@ -85,7 +85,6 @@ end --- Packed tables use this as their metatable local packedmt = {} ----@private local function unpack(t) if type(t) == 'table' and getmetatable(t) == packedmt then return _G.unpack(t, 1, t.n) @@ -93,7 +92,6 @@ local function unpack(t) return t end ----@private local function pack(...) local n = select('#', ...) if n > 1 then @@ -102,7 +100,6 @@ local function pack(...) return ... end ----@private local function sanitize(t) if type(t) == 'table' and getmetatable(t) == packedmt then -- Remove length tag @@ -120,7 +117,6 @@ end ---@param ... any Function arguments. ---@return boolean True if the iterator stage should continue, false otherwise ---@return any Function arguments. ----@private local function continue(...) if select('#', ...) > 0 then return false, ... @@ -137,7 +133,6 @@ end ---@param ... any Arguments to apply to f ---@return boolean True if the iterator pipeline should continue, false otherwise ---@return any Return values of f ----@private local function apply(f, ...) if select('#', ...) > 0 then return continue(f(...)) @@ -230,7 +225,6 @@ function Iter.map(self, f) --- values passed. ---@param ... any Values to return if cont is false. ---@return any - ---@private local function fn(cont, ...) if cont then return fn(apply(f, next(self))) @@ -270,7 +264,6 @@ end --- Takes all of the values returned by the previous stage --- in the pipeline as arguments. function Iter.each(self, f) - ---@private local function fn(...) if select('#', ...) > 0 then f(...) @@ -383,7 +376,6 @@ function Iter.fold(self, init, f) local acc = init --- Use a closure to handle var args returned from iterator - ---@private local function fn(...) if select(1, ...) ~= nil then acc = f(acc, ...) @@ -525,7 +517,6 @@ function Iter.find(self, f) local result = nil --- Use a closure to handle var args returned from iterator - ---@private local function fn(...) if select(1, ...) ~= nil then if f(...) then @@ -768,7 +759,6 @@ function Iter.any(self, pred) local any = false --- Use a closure to handle var args returned from iterator - ---@private local function fn(...) if select(1, ...) ~= nil then if pred(...) then @@ -792,7 +782,6 @@ end function Iter.all(self, pred) local all = true - ---@private local function fn(...) if select(1, ...) ~= nil then if not pred(...) then @@ -929,7 +918,6 @@ function Iter.new(src, ...) local s, var = ... --- Use a closure to handle var args returned from iterator - ---@private local function fn(...) if select(1, ...) ~= nil then var = select(1, ...) diff --git a/runtime/lua/vim/loader.lua b/runtime/lua/vim/loader.lua index f340dc85b5..4f4722b0c3 100644 --- a/runtime/lua/vim/loader.lua +++ b/runtime/lua/vim/loader.lua @@ -21,7 +21,10 @@ local M = {} ---@alias LoaderStats table<string, {total:number, time:number, [string]:number?}?> +---@nodoc M.path = vim.fn.stdpath('cache') .. '/luac' + +---@nodoc M.enabled = false ---@class Loader @@ -58,7 +61,6 @@ function Loader.get_hash(path) return Loader._hashes[path] end ----@private local function normalize(path) return vim.fs.normalize(path, { expand_env = false }) end @@ -122,7 +124,6 @@ end --- @param path string --- @param mode integer --- @return string? data ---- @private local function readfile(path, mode) local f = uv.fs_open(path, 'r', mode) if f then @@ -310,7 +311,6 @@ function M.find(modname, opts) local results = {} -- Only continue if we haven't found anything yet or we want to find all - ---@private local function continue() return #results == 0 or opts.all end @@ -318,7 +318,6 @@ function M.find(modname, opts) -- Checks if the given paths contain the top-level module. -- If so, it tries to find the module path for the given module name. ---@param paths string[] - ---@private local function _find(paths) for _, path in ipairs(paths) do if topmod == '*' then @@ -504,7 +503,6 @@ end ---@private function M._inspect(opts) if opts and opts.print then - ---@private local function ms(nsec) return math.floor(nsec / 1e6 * 1000 + 0.5) / 1000 .. 'ms' end diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua index 97aab45f2c..35e4bc9dd8 100644 --- a/runtime/lua/vim/lsp.lua +++ b/runtime/lua/vim/lsp.lua @@ -66,7 +66,6 @@ lsp._request_name_to_capability = { -- TODO improve handling of scratch buffers with LSP attached. ----@private --- Concatenates and writes a list of strings to the Vim error buffer. --- ---@param ... string List to write to the buffer @@ -75,7 +74,6 @@ local function err_message(...) nvim_command('redraw') end ----@private --- Returns the buffer number for the given {bufnr}. --- ---@param bufnr (integer|nil) Buffer number to resolve. Defaults to current buffer @@ -101,7 +99,6 @@ function lsp._unsupported_method(method) return msg end ----@private --- Checks whether a given path is a directory. --- ---@param filename (string) path to check @@ -132,7 +129,6 @@ local format_line_ending = { ['mac'] = '\r', } ----@private ---@param bufnr (number) ---@return string local function buf_get_line_ending(bufnr) @@ -140,7 +136,6 @@ local function buf_get_line_ending(bufnr) end local client_index = 0 ----@private --- Returns a new, unused client id. --- ---@return integer client_id @@ -153,7 +148,6 @@ local active_clients = {} --- @type table<integer,lsp.Client> local all_buffer_active_clients = {} --- @type table<integer,table<integer,true>> local uninitialized_clients = {} --- @type table<integer,lsp.Client> ----@private ---@param bufnr? integer ---@param fn fun(client: lsp.Client, client_id: integer, bufnr: integer) local function for_each_buffer_client(bufnr, fn, restrict_client_ids) @@ -185,9 +179,10 @@ local function for_each_buffer_client(bufnr, fn, restrict_client_ids) end end --- Error codes to be used with `on_error` from |vim.lsp.start_client|. --- Can be used to look up the string from a the number or the number --- from the string. +--- Error codes to be used with `on_error` from |vim.lsp.start_client|. +--- Can be used to look up the string from a the number or the number +--- from the string. +--- @nodoc lsp.client_errors = tbl_extend( 'error', lsp_rpc.client_errors, @@ -196,7 +191,6 @@ lsp.client_errors = tbl_extend( }) ) ----@private --- Normalizes {encoding} to valid LSP encoding names. --- ---@param encoding (string) Encoding to normalize @@ -243,7 +237,6 @@ function lsp._cmd_parts(input) return cmd, cmd_args end ----@private --- Augments a validator function with support for optional (nil) values. --- ---@param fn (fun(v): boolean) The original validator function; should return a @@ -256,7 +249,6 @@ local function optional_validator(fn) end end ----@private --- Validates a client configuration as given to |vim.lsp.start_client()|. --- ---@param config (lsp.ClientConfig) @@ -308,7 +300,6 @@ local function validate_client_config(config) return cmd, cmd_args, offset_encoding end ----@private --- Returns full text of buffer {bufnr} as a string. --- ---@param bufnr (number) Buffer handle, or 0 for current. @@ -322,7 +313,6 @@ local function buf_get_full_text(bufnr) return text end ----@private --- Memoizes a function. On first run, the function return value is saved and --- immediately returned on subsequent runs. If the function returns a multival, --- only the first returned value will be memoized and returned. The function will only be run once, @@ -382,7 +372,6 @@ do --- @field debounce integer debounce duration in ms --- @field clients table<integer, table> clients using this state. {client_id, client} - ---@private ---@param group CTGroup ---@return string local function group_key(group) @@ -403,7 +392,6 @@ do end, }) - ---@private ---@return CTGroup local function get_group(client) local allow_inc_sync = if_nil(client.config.flags.allow_incremental_sync, true) @@ -419,7 +407,6 @@ do } end - ---@private ---@param state CTBufferState local function incremental_changes(state, encoding, bufnr, firstline, lastline, new_lastline) local prev_lines = state.lines @@ -543,8 +530,6 @@ do end end - ---@private - -- -- Adjust debounce time by taking time of last didChange notification into -- consideration. If the last didChange happened more than `debounce` time ago, -- debounce can be skipped and otherwise maybe reduced. @@ -567,7 +552,6 @@ do return math.max(debounce - ms_since_last_flush, 0) end - ---@private ---@param bufnr integer ---@param sync_kind integer protocol.TextDocumentSyncKind ---@param state CTGroupState @@ -694,7 +678,6 @@ do end end ----@private --- Default handler for the 'textDocument/didOpen' LSP notification. --- ---@param bufnr integer Number of the buffer, or 0 for current @@ -924,7 +907,6 @@ function lsp.status() return message end ----@private -- Determines whether the given option can be set by `set_defaults`. local function is_empty_or_default(bufnr, option) if vim.bo[bufnr][option] == '' then @@ -1138,7 +1120,6 @@ function lsp.start_client(config) local dispatch = {} - ---@private --- Returns the handler associated with an LSP method. --- Returns the default handler if the user hasn't set a custom one. --- @@ -1208,7 +1189,6 @@ function lsp.start_client(config) end end - ---@private --- Reset defaults set by `set_defaults`. --- Must only be called if the last client attached to a buffer exits. local function reset_defaults(bufnr) @@ -1337,7 +1317,6 @@ function lsp.start_client(config) -- Store the uninitialized_clients for cleanup in case we exit before initialize finishes. uninitialized_clients[client_id] = client - ---@private local function initialize() local valid_traces = { off = 'off', @@ -1749,7 +1728,6 @@ do end end ----@private ---Buffer lifecycle handler for textDocument/didSave local function text_document_did_save_handler(bufnr) bufnr = resolve_bufnr(bufnr) @@ -2082,7 +2060,6 @@ api.nvim_create_autocmd('VimLeavePre', { local poll_time = 50 - ---@private local function check_clients_closed() for client_id, timeout in pairs(timeouts) do timeouts[client_id] = timeout - poll_time @@ -2440,12 +2417,13 @@ function lsp.buf_get_clients(bufnr) return result end --- 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 lsp.log_levels = log.levels --- Sets the global log level for LSP logging. diff --git a/runtime/lua/vim/lsp/_watchfiles.lua b/runtime/lua/vim/lsp/_watchfiles.lua index 87938fe4d5..b66f2f6f32 100644 --- 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. --- diff --git a/runtime/lua/vim/lsp/buf.lua b/runtime/lua/vim/lsp/buf.lua index 2140d3ae37..46f582dc7e 100644 --- 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' diff --git a/runtime/lua/vim/lsp/codelens.lua b/runtime/lua/vim/lsp/codelens.lua index 67104cc40b..a516238ae0 100644 --- 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 diff --git a/runtime/lua/vim/lsp/diagnostic.lua b/runtime/lua/vim/lsp/diagnostic.lua index 3efa5c51ff..c2cf7c6ba5 100644 --- 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) diff --git a/runtime/lua/vim/lsp/handlers.lua b/runtime/lua/vim/lsp/handlers.lua index 20c4d7458b..ce3db68618 100644 --- 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. diff --git a/runtime/lua/vim/lsp/inlay_hint.lua b/runtime/lua/vim/lsp/inlay_hint.lua index 6426b0c039..bec6f33e93 100644 --- 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] diff --git a/runtime/lua/vim/lsp/log.lua b/runtime/lua/vim/lsp/log.lua index 033f93bd6e..6d2e0bc292 100644 --- 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 diff --git a/runtime/lua/vim/lsp/rpc.lua b/runtime/lua/vim/lsp/rpc.lua index c110c3a67c..a77af937b3 100644 --- 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 diff --git a/runtime/lua/vim/lsp/semantic_tokens.lua b/runtime/lua/vim/lsp/semantic_tokens.lua index 191cc7b400..84723bbc05 100644 --- 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 '' diff --git a/runtime/lua/vim/lsp/sync.lua b/runtime/lua/vim/lsp/sync.lua index 350c096b47..9c1bbf3892 100644 --- 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 diff --git a/runtime/lua/vim/lsp/tagfunc.lua b/runtime/lua/vim/lsp/tagfunc.lua index eb25b67db9..c70eb573c2 100644 --- 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 diff --git a/runtime/lua/vim/lsp/util.lua b/runtime/lua/vim/lsp/util.lua index 59b9916f64..9a6114c35b 100644 --- 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 diff --git a/runtime/lua/vim/secure.lua b/runtime/lua/vim/secure.lua index 1a04e11231..837738c041 100644 --- a/runtime/lua/vim/secure.lua +++ b/runtime/lua/vim/secure.lua @@ -1,6 +1,5 @@ local M = {} ----@private --- Reads trust database from $XDG_STATE_HOME/nvim/trust. --- ---@return (table) Contents of trust database, if it exists. Empty table otherwise. @@ -22,7 +21,6 @@ local function read_trust() return trust end ----@private --- Writes provided {trust} table to trust database at --- $XDG_STATE_HOME/nvim/trust. --- diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua index dd05299295..291b003d87 100644 --- a/runtime/lua/vim/shared.lua +++ b/runtime/lua/vim/shared.lua @@ -8,6 +8,45 @@ vim = vim or {} +local function _id(v) + return v +end + +local deepcopy + +local deepcopy_funcs = { + table = function(orig, cache) + if cache[orig] then + return cache[orig] + end + local copy = {} + + cache[orig] = copy + local mt = getmetatable(orig) + for k, v in pairs(orig) do + copy[deepcopy(k, cache)] = deepcopy(v, cache) + end + return setmetatable(copy, mt) + end, + number = _id, + string = _id, + ['nil'] = _id, + boolean = _id, + ['function'] = _id, +} + +deepcopy = function(orig, _cache) + local f = deepcopy_funcs[type(orig)] + if f then + return f(orig, _cache or {}) + else + if type(orig) == 'userdata' and orig == vim.NIL then + return vim.NIL + end + error('Cannot deepcopy object of type ' .. type(orig)) + end +end + --- Returns a deep copy of the given object. Non-table objects are copied as --- in a typical Lua assignment, whereas table objects are copied recursively. --- Functions are naively copied, so functions in the copied table point to the @@ -17,45 +56,9 @@ vim = vim or {} ---@generic T: table ---@param orig T Table to copy ---@return T Table of copied keys and (nested) values. -function vim.deepcopy(orig) end -- luacheck: no unused -vim.deepcopy = (function() - local function _id(v) - return v - end - - local deepcopy_funcs = { - table = function(orig, cache) - if cache[orig] then - return cache[orig] - end - local copy = {} - - cache[orig] = copy - local mt = getmetatable(orig) - for k, v in pairs(orig) do - copy[vim.deepcopy(k, cache)] = vim.deepcopy(v, cache) - end - return setmetatable(copy, mt) - end, - number = _id, - string = _id, - ['nil'] = _id, - boolean = _id, - ['function'] = _id, - } - - return function(orig, cache) - local f = deepcopy_funcs[type(orig)] - if f then - return f(orig, cache or {}) - else - if type(orig) == 'userdata' and orig == vim.NIL then - return vim.NIL - end - error('Cannot deepcopy object of type ' .. type(orig)) - end - end -end)() +function vim.deepcopy(orig) + return deepcopy(orig) +end --- Splits a string at each instance of a separator. --- @@ -318,7 +321,6 @@ function vim.tbl_isempty(t) end --- We only merge empty tables or tables that are not an array (indexed by integers) ----@private local function can_merge(v) return type(v) == 'table' and (vim.tbl_isempty(v) or not vim.tbl_isarray(v)) end @@ -770,7 +772,6 @@ 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)) diff --git a/runtime/lua/vim/treesitter.lua b/runtime/lua/vim/treesitter.lua index 5526c9858c..8bd85d3734 100644 --- a/runtime/lua/vim/treesitter.lua +++ b/runtime/lua/vim/treesitter.lua @@ -39,7 +39,10 @@ local M = setmetatable({}, { end, }) +--- @nodoc M.language_version = vim._ts_get_language_version() + +--- @nodoc M.minimum_language_version = vim._ts_get_minimum_language_version() --- Creates a new parser @@ -60,12 +63,10 @@ function M._create_parser(bufnr, lang, opts) local self = LanguageTree.new(bufnr, lang, opts) - ---@private local function bytes_cb(_, ...) self:_on_bytes(...) end - ---@private local function detach_cb(_, ...) if parsers[bufnr] == self then parsers[bufnr] = nil @@ -73,7 +74,6 @@ function M._create_parser(bufnr, lang, opts) self:_on_detach(...) end - ---@private local function reload_cb(_) self:_on_reload() end @@ -91,7 +91,6 @@ function M._create_parser(bufnr, lang, opts) return self end ---- @private local function valid_lang(lang) return lang and lang ~= '' end @@ -205,7 +204,6 @@ function M.get_range(node, source, metadata) return { node:range(true) } end ----@private ---@param buf integer ---@param range Range ---@returns string diff --git a/runtime/lua/vim/treesitter/dev.lua b/runtime/lua/vim/treesitter/dev.lua index 99cd147658..1bb5a08205 100644 --- a/runtime/lua/vim/treesitter/dev.lua +++ b/runtime/lua/vim/treesitter/dev.lua @@ -42,7 +42,6 @@ local TSTreeView = {} ---@param injections table<integer,TSP.Node> Mapping of node ids to root nodes of injected language trees (see --- explanation above) ---@param tree TSP.Node[] Output table containing a list of tables each representing a node in the tree ----@private local function traverse(node, depth, lang, injections, tree) local injection = injections[node:id()] if injection then @@ -141,7 +140,6 @@ end local decor_ns = api.nvim_create_namespace('ts.dev') ----@private ---@param lnum integer ---@param col integer ---@param end_lnum integer diff --git a/runtime/lua/vim/treesitter/highlighter.lua b/runtime/lua/vim/treesitter/highlighter.lua index d4db6bc404..f8ec5b175d 100644 --- a/runtime/lua/vim/treesitter/highlighter.lua +++ b/runtime/lua/vim/treesitter/highlighter.lua @@ -17,6 +17,7 @@ local query = vim.treesitter.query local TSHighlighter = rawget(vim.treesitter, 'TSHighlighter') or {} TSHighlighter.__index = TSHighlighter +--- @nodoc TSHighlighter.active = TSHighlighter.active or {} ---@class TSHighlighterQuery @@ -205,7 +206,6 @@ function TSHighlighter:get_query(lang) return self._queries[lang] end ----@private ---@param self TSHighlighter ---@param buf integer ---@param line integer diff --git a/runtime/lua/vim/treesitter/language.lua b/runtime/lua/vim/treesitter/language.lua index 08c297c9ad..9695e2c41c 100644 --- a/runtime/lua/vim/treesitter/language.lua +++ b/runtime/lua/vim/treesitter/language.lua @@ -104,7 +104,6 @@ function M.add(lang, opts) vim._ts_add_language(path, lang, symbol_name) end ---- @private --- @param x string|string[] --- @return string[] local function ensure_list(x) diff --git a/runtime/lua/vim/treesitter/languagetree.lua b/runtime/lua/vim/treesitter/languagetree.lua index bf6333aaa4..0d4a1a54dd 100644 --- a/runtime/lua/vim/treesitter/languagetree.lua +++ b/runtime/lua/vim/treesitter/languagetree.lua @@ -164,7 +164,6 @@ function LanguageTree:_set_logger() self._parser:_set_logger(log_lex, log_parse, self._logger) end ----@private ---Measure execution time of a function ---@generic R1, R2, R3 ---@param f fun(): R1, R2, R2 @@ -444,7 +443,6 @@ function LanguageTree:destroy() end end ----@private ---@param region Range6[] local function region_tostr(region) if #region == 0 then @@ -560,7 +558,6 @@ function LanguageTree:included_regions() return regions end ----@private ---@param node TSNode ---@param source string|integer ---@param metadata TSMetadata @@ -600,7 +597,6 @@ end ---@alias TSInjection table<string,table<integer,TSInjectionElem>> ----@private ---@param t table<integer,TSInjection> ---@param tree_index integer ---@param pattern integer @@ -963,7 +959,6 @@ function LanguageTree:register_cbs(cbs, recursive) end end ----@private ---@param tree TSTree ---@param range Range ---@return boolean diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua index 7610ef7b7f..08186468a5 100644 --- a/runtime/lua/vim/treesitter/query.lua +++ b/runtime/lua/vim/treesitter/query.lua @@ -15,7 +15,6 @@ Query.__index = Query ---@class TSQueryModule local M = {} ----@private ---@param files string[] ---@return string[] local function dedupe_files(files) @@ -33,7 +32,6 @@ local function dedupe_files(files) return result end ----@private local function safe_read(filename, read_quantifier) local file, err = io.open(filename, 'r') if not file then @@ -44,7 +42,6 @@ local function safe_read(filename, read_quantifier) return content end ----@private --- Adds {ilang} to {base_langs}, only if {ilang} is different than {lang} --- ---@return boolean true If lang == ilang @@ -153,7 +150,6 @@ function M.get_files(lang, query_name, is_included) return query_files end ----@private ---@param filenames string[] ---@return string local function read_query_files(filenames) @@ -335,7 +331,6 @@ local predicate_handlers = { ['match?'] = (function() local magic_prefixes = { ['\\v'] = true, ['\\m'] = true, ['\\M'] = true, ['\\V'] = true } - ---@private local function check_magic(str) if string.len(str) < 2 or magic_prefixes[string.sub(str, 1, 2)] then return str @@ -624,12 +619,10 @@ function M.list_predicates() return vim.tbl_keys(predicate_handlers) end ----@private local function xor(x, y) return (x or y) and not (x and y) end ----@private local function is_directive(name) return string.sub(name, -1) == '!' end @@ -700,7 +693,6 @@ end --- Returns the start and stop value if set else the node's range. -- When the node's range is used, the stop is incremented by 1 -- to make the search inclusive. ----@private ---@param start integer ---@param stop integer ---@param node TSNode @@ -750,7 +742,6 @@ function Query:iter_captures(node, source, start, stop) start, stop = value_or_node_range(start, stop, node) local raw_iter = node:_rawquery(self.query, true, start, stop) - ---@private local function iter() local capture, captured_node, match = raw_iter() local metadata = {} diff --git a/runtime/lua/vim/uri.lua b/runtime/lua/vim/uri.lua index dec7840eb0..eaa64a6fad 100644 --- a/runtime/lua/vim/uri.lua +++ b/runtime/lua/vim/uri.lua @@ -8,7 +8,6 @@ do local schar = string.char --- Convert hex to char - ---@private local function hex_to_char(hex) return schar(tonumber(hex, 16)) end @@ -33,7 +32,6 @@ do local sbyte = string.byte local tohex = require('bit').tohex - ---@private local function percent_encode_char(char) return '%' .. tohex(sbyte(char), 2) end @@ -46,15 +44,16 @@ do end end ----@private local function is_windows_file_uri(uri) return uri:match('^file:/+[a-zA-Z]:') ~= nil end +local M = {} + --- Get a URI from a file path. ---@param path string Path to file ---@return string URI -local function uri_from_fname(path) +function M.uri_from_fname(path) local volume_path, fname = path:match('^([a-zA-Z]:)(.*)') local is_windows = volume_path ~= nil if is_windows then @@ -76,7 +75,7 @@ local WINDOWS_URI_SCHEME_PATTERN = '^([a-zA-Z]+[a-zA-Z0-9.+-]*):[a-zA-Z]:.*' --- Get a URI from a bufnr ---@param bufnr integer ---@return string URI -local function uri_from_bufnr(bufnr) +function M.uri_from_bufnr(bufnr) local fname = vim.api.nvim_buf_get_name(bufnr) local volume_path = fname:match('^([a-zA-Z]:).*') local is_windows = volume_path ~= nil @@ -90,14 +89,14 @@ local function uri_from_bufnr(bufnr) if scheme then return fname else - return uri_from_fname(fname) + return M.uri_from_fname(fname) end end --- Get a filename from a URI ---@param uri string ---@return string filename or unchanged URI for non-file URIs -local function uri_to_fname(uri) +function M.uri_to_fname(uri) local scheme = assert(uri:match(URI_SCHEME_PATTERN), 'URI must contain a scheme: ' .. uri) if scheme ~= 'file' then return uri @@ -118,13 +117,8 @@ end -- ---@param uri string ---@return integer bufnr -local function uri_to_bufnr(uri) - return vim.fn.bufadd(uri_to_fname(uri)) +function M.uri_to_bufnr(uri) + return vim.fn.bufadd(M.uri_to_fname(uri)) end -return { - uri_from_fname = uri_from_fname, - uri_from_bufnr = uri_from_bufnr, - uri_to_fname = uri_to_fname, - uri_to_bufnr = uri_to_bufnr, -} +return M diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua index 8ff8a19cb9..96889438eb 100644 --- a/runtime/lua/vim/version.lua +++ b/runtime/lua/vim/version.lua @@ -65,8 +65,6 @@ local M = {} local Version = {} Version.__index = Version ---- @private ---- --- Compares prerelease strings: per semver, number parts must be must be treated as numbers: --- "pre1.10" is greater than "pre1.2". https://semver.org/#spec-item-11 local function cmp_prerel(prerel1, prerel2) @@ -332,7 +330,6 @@ function M.range(spec) -- Adapted from https://github.com/folke/lazy.nvim end end ----@private ---@param v string|Version ---@return string local function create_err_msg(v) diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py index 0a7dd6e9ab..dfad1f000c 100755 --- a/scripts/gen_vimdoc.py +++ b/scripts/gen_vimdoc.py @@ -135,7 +135,7 @@ CONFIG = { # Section helptag. 'helptag_fmt': lambda name: f'*api-{name.lower()}*', # Per-function helptag. - 'fn_helptag_fmt': lambda fstem, name: f'*{name}()*', + 'fn_helptag_fmt': lambda fstem, name, istbl: f'*{name}()*', # Module name overrides (for Lua). 'module_override': {}, # Append the docs for these modules, do not start a new section. @@ -193,6 +193,7 @@ CONFIG = { 'fn_name_fmt': lambda fstem, name: ( name if fstem in [ 'vim.iter' ] else f'vim.{name}' if fstem in [ '_editor', 'vim.regex'] else + f'vim.{name}' if fstem == '_options' and not name[0].isupper() else f'{fstem}.{name}' if fstem.startswith('vim') else name ), @@ -210,14 +211,15 @@ CONFIG = { '*lua-vim*' if name.lower() == '_editor' else '*lua-vimscript*' if name.lower() == '_options' else f'*vim.{name.lower()}*'), - 'fn_helptag_fmt': lambda fstem, name: ( + 'fn_helptag_fmt': lambda fstem, name, istbl: ( f'*vim.opt:{name.split(":")[-1]}()*' if ':' in name and name.startswith('Option') else # Exclude fstem for methods f'*{name}()*' if ':' in name else f'*vim.{name}()*' if fstem.lower() == '_editor' else + f'*vim.{name}*' if fstem.lower() == '_options' and istbl else # Prevents vim.regex.regex f'*{fstem}()*' if fstem.endswith('.' + name) else - f'*{fstem}.{name}()*' + f'*{fstem}.{name}{"" if istbl else "()"}*' ), 'module_override': { # `shared` functions are exposed on the `vim` module. @@ -275,14 +277,11 @@ CONFIG = { '*lsp-core*' if name.lower() == 'lsp' else f'*lsp-{name.lower()}*'), - 'fn_helptag_fmt': lambda fstem, name: ( - f'*vim.lsp.{name}()*' - if fstem == 'lsp' and name != 'client' - else ( - '*vim.lsp.client*' - # HACK. TODO(justinmk): class/structure support in lua2dox - if 'lsp.client' == f'{fstem}.{name}' - else f'*vim.lsp.{fstem}.{name}()*')), + 'fn_helptag_fmt': lambda fstem, name, istbl: ( + f'*vim.lsp.{name}{"" if istbl else "()"}*' if fstem == 'lsp' and name != 'client' else + # HACK. TODO(justinmk): class/structure support in lua2dox + '*vim.lsp.client*' if 'lsp.client' == f'{fstem}.{name}' else + f'*vim.lsp.{fstem}.{name}{"" if istbl else "()"}*'), 'module_override': {}, 'append_only': [], }, @@ -295,10 +294,11 @@ CONFIG = { 'files': ['runtime/lua/vim/diagnostic.lua'], 'file_patterns': '*.lua', 'fn_name_prefix': '', + 'include_tables': False, 'section_name': {'diagnostic.lua': 'diagnostic'}, 'section_fmt': lambda _: 'Lua module: vim.diagnostic', 'helptag_fmt': lambda _: '*diagnostic-api*', - 'fn_helptag_fmt': lambda fstem, name: f'*vim.{fstem}.{name}()*', + 'fn_helptag_fmt': lambda fstem, name, istbl: f'*vim.{fstem}.{name}{"" if istbl else "()"}*', 'module_override': {}, 'append_only': [], }, @@ -328,7 +328,7 @@ CONFIG = { '*lua-treesitter-core*' if name.lower() == 'treesitter' else f'*lua-treesitter-{name.lower()}*'), - 'fn_helptag_fmt': lambda fstem, name: ( + 'fn_helptag_fmt': lambda fstem, name, istbl: ( f'*vim.{fstem}.{name}()*' if fstem == 'treesitter' else f'*{name}()*' @@ -842,6 +842,13 @@ def extract_from_xml(filename, target, width, fmt_vimhelp): if return_type == '': continue + if 'local_function' in return_type: # Special from lua2dox.lua. + continue + + istbl = return_type.startswith('table') # Special from lua2dox.lua. + if istbl and not CONFIG[target].get('include_tables', True): + continue + if return_type.startswith(('ArrayOf', 'DictionaryOf')): parts = return_type.strip('_').split('_') return_type = '{}({})'.format(parts[0], ', '.join(parts[1:])) @@ -904,15 +911,20 @@ def extract_from_xml(filename, target, width, fmt_vimhelp): if '.' in compoundname: fstem = compoundname.split('.')[0] fstem = CONFIG[target]['module_override'].get(fstem, fstem) - vimtag = CONFIG[target]['fn_helptag_fmt'](fstem, name) + vimtag = CONFIG[target]['fn_helptag_fmt'](fstem, name, istbl) if 'fn_name_fmt' in CONFIG[target]: name = CONFIG[target]['fn_name_fmt'](fstem, name) - prefix = '%s(' % name - suffix = '%s)' % ', '.join('{%s}' % a[1] for a in params - if a[0] not in ('void', 'Error', 'Arena', - 'lua_State')) + if istbl: + aopen, aclose = '', '' + else: + aopen, aclose = '(', ')' + + prefix = name + aopen + suffix = ', '.join('{%s}' % a[1] for a in params + if a[0] not in ('void', 'Error', 'Arena', + 'lua_State')) + aclose if not fmt_vimhelp: c_decl = '%s %s(%s);' % (return_type, name, ', '.join(c_args)) diff --git a/scripts/lua2dox.lua b/scripts/lua2dox.lua index be72b9e1c0..9a666ea629 100644 --- a/scripts/lua2dox.lua +++ b/scripts/lua2dox.lua @@ -160,6 +160,7 @@ end local function process_magic(line, generics) line = line:gsub('^%s+@', '@') line = line:gsub('@package', '@private') + line = line:gsub('@nodoc', '@private') if not vim.startswith(line, '@') then -- it's a magic comment return '/// ' .. line @@ -327,6 +328,11 @@ local function process_function_header(line) .. fn:sub(paren_start + 1) end + if line:match('local') then + -- Special: tell gen_vimdoc.py this is a local function. + return 'local_function ' .. fn .. '{}' + end + -- add vanilla function return 'function ' .. fn .. '{}' end @@ -336,6 +342,9 @@ end --- @param generics table<string,string>> --- @return string? local function process_line(line, in_stream, generics) + local line_raw = line + line = vim.trim(line) + if vim.startswith(line, '---') then return process_magic(line:sub(4), generics) end @@ -348,6 +357,14 @@ local function process_line(line, in_stream, generics) return process_function_header(line) end + if not line:match('^local') then + local v = line_raw:match('^([A-Za-z][.a-zA-Z_]*)%s+%=') + if v and v:match('%.') then + -- Special: this lets gen_vimdoc.py handle tables. + return 'table '..v..'() {}' + end + end + if #line > 0 then -- we don't know what this line means, so just comment it out return '// zz: ' .. line end @@ -363,11 +380,11 @@ function Lua2DoxFilter:filter(filename) local generics = {} --- @type table<string,string> while not in_stream:eof() do - local line = vim.trim(in_stream:getLine()) + local line = in_stream:getLine() local out_line = process_line(line, in_stream, generics) - if not vim.startswith(line, '---') then + if not vim.startswith(vim.trim(line), '---') then generics = {} end |