diff options
| author | Lewis Russell <lewis6991@gmail.com> | 2024-02-15 17:16:04 +0000 |
|---|---|---|
| committer | Lewis Russell <me@lewisr.dev> | 2024-02-27 14:41:17 +0000 |
| commit | 9beb40a4db5613601fc1a4b828a44e5977eca046 (patch) | |
| tree | 314096d28ccdf2a2b035091783baa35193887d6a /runtime/lua/vim | |
| parent | 7ad2e3c64562bfb0ea2f7be305e4b0e6d2474d64 (diff) | |
| download | rneovim-9beb40a4db5613601fc1a4b828a44e5977eca046.tar.gz rneovim-9beb40a4db5613601fc1a4b828a44e5977eca046.tar.bz2 rneovim-9beb40a4db5613601fc1a4b828a44e5977eca046.zip | |
feat(docs): replace lua2dox.lua
Problem:
The documentation flow (`gen_vimdoc.py`) has several issues:
- it's not very versatile
- depends on doxygen
- doesn't work well with Lua code as it requires an awkward filter script to convert it into pseudo-C.
- The intermediate XML files and filters makes it too much like a rube goldberg machine.
Solution:
Re-implement the flow using Lua, LPEG and treesitter.
- `gen_vimdoc.py` is now replaced with `gen_vimdoc.lua` and replicates a portion of the logic.
- `lua2dox.lua` is gone!
- No more XML files.
- Doxygen is now longer used and instead we now use:
- LPEG for comment parsing (see `scripts/luacats_grammar.lua` and `scripts/cdoc_grammar.lua`).
- LPEG for C parsing (see `scripts/cdoc_parser.lua`)
- Lua patterns for Lua parsing (see `scripts/luacats_parser.lua`).
- Treesitter for Markdown parsing (see `scripts/text_utils.lua`).
- The generated `runtime/doc/*.mpack` files have been removed.
- `scripts/gen_eval_files.lua` now instead uses `scripts/cdoc_parser.lua` directly.
- Text wrapping is implemented in `scripts/text_utils.lua` and appears to produce more consistent results (the main contributer to the diff of this change).
Diffstat (limited to 'runtime/lua/vim')
35 files changed, 1009 insertions, 911 deletions
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua index c5a6e65e86..4e39abb2be 100644 --- a/runtime/lua/vim/_editor.lua +++ b/runtime/lua/vim/_editor.lua @@ -127,10 +127,10 @@ vim.log = { --- timeout the process is sent the KILL signal (9) and the exit code is set to 124. Cannot --- be called in |api-fast|. --- - SystemCompleted is an object with the fields: ---- - code: (integer) ---- - signal: (integer) ---- - stdout: (string), nil if stdout argument is passed ---- - stderr: (string), nil if stderr argument is passed +--- - code: (integer) +--- - signal: (integer) +--- - stdout: (string), nil if stdout argument is passed +--- - stderr: (string), nil if stderr argument is passed --- - kill (fun(signal: integer|string)) --- - write (fun(data: string|nil)) Requires `stdin=true`. Pass `nil` to close the stream. --- - is_closing (fun(): boolean) @@ -706,8 +706,8 @@ end --- Generates a list of possible completions for the string. --- String has the pattern. --- ---- 1. Can we get it to just return things in the global namespace with that name prefix ---- 2. Can we get it to return things from global namespace even with `print(` in front. +--- 1. Can we get it to just return things in the global namespace with that name prefix +--- 2. Can we get it to return things from global namespace even with `print(` in front. --- --- @param pat string function vim._expand_pat(pat, env) @@ -885,6 +885,7 @@ do --- similar to the builtin completion for the `:lua` command. --- --- Activate using `set omnifunc=v:lua.vim.lua_omnifunc` in a Lua buffer. + --- @param find_start 1|0 function vim.lua_omnifunc(find_start, _) if find_start == 1 then local line = vim.api.nvim_get_current_line() @@ -914,6 +915,7 @@ end --- --- @see |vim.inspect()| --- @see |:=| +--- @param ... any --- @return any # given arguments. function vim.print(...) if vim.in_fast_event() then diff --git a/runtime/lua/vim/_inspector.lua b/runtime/lua/vim/_inspector.lua index 3f7b9d2c23..9a073c32c4 100644 --- a/runtime/lua/vim/_inspector.lua +++ b/runtime/lua/vim/_inspector.lua @@ -17,7 +17,7 @@ local defaults = { ---@param bufnr? integer defaults to the current buffer ---@param row? integer row to inspect, 0-based. Defaults to the row of the current cursor ---@param col? integer col to inspect, 0-based. Defaults to the col of the current cursor ----@param filter? InspectorFilter (table|nil) a table with key-value pairs to filter the items +---@param filter? InspectorFilter (table) a table with key-value pairs to filter the items --- - syntax (boolean): include syntax based highlight groups (defaults to true) --- - treesitter (boolean): include treesitter based highlight groups (defaults to true) --- - extmarks (boolean|"all"): include extmarks. When `all`, then extmarks without a `hl_group` will also be included (defaults to true) @@ -139,7 +139,7 @@ end ---@param bufnr? integer defaults to the current buffer ---@param row? integer row to inspect, 0-based. Defaults to the row of the current cursor ---@param col? integer col to inspect, 0-based. Defaults to the col of the current cursor ----@param filter? InspectorFilter (table|nil) see |vim.inspect_pos()| +---@param filter? InspectorFilter (table) see |vim.inspect_pos()| function vim.show_pos(bufnr, row, col, filter) local items = vim.inspect_pos(bufnr, row, col, filter) diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index aee866f324..d2f624fd97 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -38,6 +38,7 @@ function vim.api.nvim__get_runtime(pat, all, opts) end --- @private --- Returns object given as argument. +--- --- This API function is used for testing. One should not rely on its presence --- in plugins. --- @@ -47,6 +48,7 @@ function vim.api.nvim__id(obj) end --- @private --- Returns array given as argument. +--- --- This API function is used for testing. One should not rely on its presence --- in plugins. --- @@ -56,6 +58,7 @@ function vim.api.nvim__id_array(arr) end --- @private --- Returns dictionary given as argument. +--- --- This API function is used for testing. One should not rely on its presence --- in plugins. --- @@ -65,6 +68,7 @@ function vim.api.nvim__id_dictionary(dct) end --- @private --- Returns floating-point value given as argument. +--- --- This API function is used for testing. One should not rely on its presence --- in plugins. --- @@ -108,17 +112,20 @@ function vim.api.nvim__stats() end function vim.api.nvim__unpack(str) end --- Adds a highlight to buffer. +--- --- Useful for plugins that dynamically generate highlights to a buffer (like --- a semantic highlighter or linter). The function adds a single highlight to --- a buffer. Unlike `matchaddpos()` highlights follow changes to line --- numbering (as lines are inserted/removed above the highlighted line), like --- signs and marks do. +--- --- Namespaces are used for batch deletion/updating of a set of highlights. To --- create a namespace, use `nvim_create_namespace()` which returns a --- namespace id. Pass it in to this function as `ns_id` to add highlights to --- the namespace. All highlights in the same namespace can then be cleared --- with single call to `nvim_buf_clear_namespace()`. If the highlight never --- will be deleted by an API call, pass `ns_id = -1`. +--- --- As a shorthand, `ns_id = 0` can be used to create a new namespace for the --- highlight, the allocated id is then returned. If `hl_group` is the empty --- string no highlight is added, but a new `ns_id` is still returned. This is @@ -131,11 +138,12 @@ function vim.api.nvim__unpack(str) end --- @param line integer Line to highlight (zero-indexed) --- @param col_start integer Start of (byte-indexed) column range to highlight --- @param col_end integer End of (byte-indexed) column range to highlight, or -1 to ---- highlight to end of line +--- highlight to end of line --- @return integer function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start, col_end) end --- Activates buffer-update events on a channel, or as Lua callbacks. +--- --- Example (Lua): capture buffer updates in a global `events` variable (use --- "vim.print(events)" to see its contents): --- @@ -148,6 +156,7 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- }) --- ``` --- +--- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param send_buffer boolean True if the initial notification should contain the --- whole buffer: first notification will be @@ -155,77 +164,70 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- will be `nvim_buf_changedtick_event`. Not for Lua --- callbacks. --- @param opts vim.api.keyset.buf_attach Optional parameters. ---- • on_lines: Lua callback invoked on change. Return a ---- truthy value (not `false` or `nil`) ---- to detach. Args: ---- • the string "lines" ---- • buffer handle ---- • b:changedtick ---- • first line that changed (zero-indexed) ---- • last line that was changed ---- • last line in the updated range ---- • byte count of previous contents ---- • deleted_codepoints (if `utf_sizes` is true) ---- • deleted_codeunits (if `utf_sizes` is true) ---- ---- • on_bytes: Lua callback invoked on change. This ---- callback receives more granular information about the ---- change compared to on_lines. Return a truthy value ---- (not `false` or `nil`) to ---- detach. Args: ---- • the string "bytes" ---- • buffer handle ---- • b:changedtick ---- • start row of the changed text (zero-indexed) ---- • start column of the changed text ---- • byte offset of the changed text (from the start of ---- the buffer) ---- • old end row of the changed text (offset from start ---- row) ---- • old end column of the changed text (if old end row ---- = 0, offset from start column) ---- • old end byte length of the changed text ---- • new end row of the changed text (offset from start ---- row) ---- • new end column of the changed text (if new end row ---- = 0, offset from start column) ---- • new end byte length of the changed text ---- ---- • on_changedtick: Lua callback invoked on changedtick ---- increment without text change. Args: ---- • the string "changedtick" ---- • buffer handle ---- • b:changedtick ---- ---- • on_detach: Lua callback invoked on detach. Args: ---- • the string "detach" ---- • buffer handle ---- ---- • on_reload: Lua callback invoked on reload. The entire ---- buffer content should be considered changed. Args: ---- • the string "reload" ---- • buffer handle ---- ---- • utf_sizes: include UTF-32 and UTF-16 size of the ---- replaced region, as args to `on_lines`. ---- • preview: also attach to command preview (i.e. ---- 'inccommand') events. +--- • on_lines: Lua callback invoked on change. Return a truthy +--- value (not `false` or `nil`) to detach. Args: +--- • the string "lines" +--- • buffer handle +--- • b:changedtick +--- • first line that changed (zero-indexed) +--- • last line that was changed +--- • last line in the updated range +--- • byte count of previous contents +--- • deleted_codepoints (if `utf_sizes` is true) +--- • deleted_codeunits (if `utf_sizes` is true) +--- • on_bytes: Lua callback invoked on change. This callback +--- receives more granular information about the change compared +--- to on_lines. Return a truthy value (not `false` or `nil`) to +--- detach. Args: +--- • the string "bytes" +--- • buffer handle +--- • b:changedtick +--- • start row of the changed text (zero-indexed) +--- • start column of the changed text +--- • byte offset of the changed text (from the start of the +--- buffer) +--- • old end row of the changed text (offset from start row) +--- • old end column of the changed text (if old end row = 0, +--- offset from start column) +--- • old end byte length of the changed text +--- • new end row of the changed text (offset from start row) +--- • new end column of the changed text (if new end row = 0, +--- offset from start column) +--- • new end byte length of the changed text +--- • on_changedtick: Lua callback invoked on changedtick +--- increment without text change. Args: +--- • the string "changedtick" +--- • buffer handle +--- • b:changedtick +--- • on_detach: Lua callback invoked on detach. Args: +--- • the string "detach" +--- • buffer handle +--- • on_reload: Lua callback invoked on reload. The entire buffer +--- content should be considered changed. Args: +--- • the string "reload" +--- • buffer handle +--- • utf_sizes: include UTF-32 and UTF-16 size of the replaced +--- region, as args to `on_lines`. +--- • preview: also attach to command preview (i.e. 'inccommand') +--- events. --- @return boolean function vim.api.nvim_buf_attach(buffer, send_buffer, opts) end --- call a function with buffer as temporary current buffer +--- --- This temporarily switches current buffer to "buffer". If the current --- window already shows "buffer", the window is not switched If a window --- inside the current tabpage (including a float) already shows the buffer --- One of these windows will be set as current window temporarily. Otherwise --- a temporary scratch window (called the "autocmd window" for historical --- reasons) will be used. +--- --- This is useful e.g. to call Vimscript functions that only work with the --- current buffer/window currently, like `termopen()`. --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param fun function Function to call inside the buffer (currently Lua callable ---- only) +--- only) --- @return any function vim.api.nvim_buf_call(buffer, fun) end @@ -238,14 +240,15 @@ function vim.api.nvim_buf_clear_highlight(buffer, ns_id, line_start, line_end) e --- Clears `namespace`d objects (highlights, `extmarks`, virtual text) from a --- region. +--- --- Lines are 0-indexed. `api-indexing` To clear the namespace in the entire --- buffer, specify line_start=0 and line_end=-1. --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param ns_id integer Namespace to clear, or -1 to clear all namespaces. --- @param line_start integer Start of range of lines to clear ---- @param line_end integer End of range of lines to clear (exclusive) or -1 to ---- clear to end of buffer. +--- @param line_end integer End of range of lines to clear (exclusive) or -1 to clear +--- to end of buffer. function vim.api.nvim_buf_clear_namespace(buffer, ns_id, line_start, line_end) end --- Creates a buffer-local command `user-commands`. @@ -279,6 +282,7 @@ function vim.api.nvim_buf_del_keymap(buffer, mode, lhs) end function vim.api.nvim_buf_del_mark(buffer, name) end --- Delete a buffer-local user-defined command. +--- --- Only commands created with `:command-buffer` or --- `nvim_buf_create_user_command()` can be deleted with this function. --- @@ -296,8 +300,8 @@ function vim.api.nvim_buf_del_var(buffer, name) end --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param opts vim.api.keyset.buf_delete Optional parameters. Keys: ---- • force: Force deletion and ignore unsaved changes. ---- • unload: Unloaded only, do not delete. See `:bunload` +--- • force: Force deletion and ignore unsaved changes. +--- • unload: Unloaded only, do not delete. See `:bunload` function vim.api.nvim_buf_delete(buffer, opts) end --- Gets a changed tick of a buffer @@ -319,14 +323,15 @@ function vim.api.nvim_buf_get_commands(buffer, opts) end --- @param ns_id integer Namespace id from `nvim_create_namespace()` --- @param id integer Extmark id --- @param opts vim.api.keyset.get_extmark Optional parameters. Keys: ---- • details: Whether to include the details dict ---- • hl_name: Whether to include highlight group name instead ---- of id, true if omitted +--- • details: Whether to include the details dict +--- • hl_name: Whether to include highlight group name instead of +--- id, true if omitted --- @return vim.api.keyset.get_extmark_item function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end --- Gets `extmarks` in "traversal order" from a `charwise` region defined by --- buffer positions (inclusive, 0-indexed `api-indexing`). +--- --- Region can be given as (row,col) tuples, or valid extmark ids (whose --- positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1) --- respectively, thus the following are equivalent: @@ -338,12 +343,15 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end --- --- If `end` is less than `start`, traversal works backwards. (Useful with --- `limit`, to get the first marks prior to a given position.) +--- --- Note: when using extmark ranges (marks with a end_row/end_col position) --- the `overlap` option might be useful. Otherwise only the start position of --- an extmark will be considered. +--- --- Note: legacy signs placed through the `:sign` commands are implemented as --- extmarks and will show up here. Their details array will contain a --- `sign_name` field. +--- --- Example: --- --- ```lua @@ -361,23 +369,23 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end --- vim.print(ms) --- ``` --- +--- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param ns_id integer Namespace id from `nvim_create_namespace()` or -1 for all ---- namespaces +--- namespaces --- @param start any Start of range: a 0-indexed (row, col) or valid extmark id ---- (whose position defines the bound). `api-indexing` +--- (whose position defines the bound). `api-indexing` --- @param end_ any End of range (inclusive): a 0-indexed (row, col) or valid ---- extmark id (whose position defines the bound). ---- `api-indexing` +--- extmark id (whose position defines the bound). `api-indexing` --- @param opts vim.api.keyset.get_extmarks Optional parameters. Keys: ---- • limit: Maximum number of marks to return ---- • details: Whether to include the details dict ---- • hl_name: Whether to include highlight group name instead ---- of id, true if omitted ---- • overlap: Also include marks which overlap the range, even ---- if their start position is less than `start` ---- • type: Filter marks by type: "highlight", "sign", ---- "virt_text" and "virt_lines" +--- • limit: Maximum number of marks to return +--- • details: Whether to include the details dict +--- • hl_name: Whether to include highlight group name instead of +--- id, true if omitted +--- • overlap: Also include marks which overlap the range, even if +--- their start position is less than `start` +--- • type: Filter marks by type: "highlight", "sign", "virt_text" +--- and "virt_lines" --- @return vim.api.keyset.get_extmark_item[] function vim.api.nvim_buf_get_extmarks(buffer, ns_id, start, end_, opts) end @@ -389,9 +397,11 @@ function vim.api.nvim_buf_get_extmarks(buffer, ns_id, start, end_, opts) end function vim.api.nvim_buf_get_keymap(buffer, mode) end --- Gets a line-range from the buffer. +--- --- Indexing is zero-based, end-exclusive. Negative indices are interpreted as --- length+1+index: -1 refers to the index past the end. So to get the last --- element use start=-2 and end=-1. +--- --- Out-of-bounds indices are clamped to the nearest valid value, unless --- `strict_indexing` is set. --- @@ -405,6 +415,7 @@ function vim.api.nvim_buf_get_lines(buffer, start, end_, strict_indexing) end --- Returns a `(row,col)` tuple representing the position of the named mark. --- "End of line" column position is returned as `v:maxcol` (big number). See --- `mark-motions`. +--- --- Marks are (1,0)-indexed. `api-indexing` --- --- @param buffer integer Buffer handle, or 0 for current buffer @@ -424,10 +435,12 @@ function vim.api.nvim_buf_get_name(buffer) end function vim.api.nvim_buf_get_number(buffer) end --- Returns the byte offset of a line (0-indexed). `api-indexing` +--- --- Line 1 (index=0) has offset 0. UTF-8 bytes are counted. EOL is one byte. --- 'fileformat' and 'fileencoding' are ignored. The line index just after the --- last line gives the total byte-count of the buffer. A final EOL byte is --- counted if it would be written, see 'eol'. +--- --- Unlike `line2byte()`, throws error for out-of-bounds indexing. Returns -1 --- for unloaded buffer. --- @@ -443,10 +456,13 @@ function vim.api.nvim_buf_get_offset(buffer, index) end function vim.api.nvim_buf_get_option(buffer, name) end --- Gets a range from the buffer. +--- --- This differs from `nvim_buf_get_lines()` in that it allows retrieving only --- portions of a line. +--- --- Indexing is zero-based. Row indices are end-inclusive, and column indices --- are end-exclusive. +--- --- Prefer `nvim_buf_get_lines()` when retrieving entire lines. --- --- @param buffer integer Buffer handle, or 0 for current buffer @@ -485,13 +501,16 @@ function vim.api.nvim_buf_is_valid(buffer) end function vim.api.nvim_buf_line_count(buffer) end --- Creates or updates an `extmark`. +--- --- By default a new extmark is created when no id is passed in, but it is --- also possible to create a new mark by passing in a previously unused id or --- move an existing mark by passing in its id. The caller must then keep --- track of existing and unused ids itself. (Useful over RPC, to avoid --- waiting for the return value.) +--- --- Using the optional arguments, it is possible to use this to highlight a --- range of text, and also to associate virtual text to the mark. +--- --- If present, the position defined by `end_col` and `end_row` should be --- after the start position in order for the extmark to cover a range. An --- earlier end position is not an error, but then it behaves like an empty @@ -502,114 +521,110 @@ function vim.api.nvim_buf_line_count(buffer) end --- @param line integer Line where to place the mark, 0-based. `api-indexing` --- @param col integer Column where to place the mark, 0-based. `api-indexing` --- @param opts vim.api.keyset.set_extmark Optional parameters. ---- • id : id of the extmark to edit. ---- • end_row : ending line of the mark, 0-based inclusive. ---- • end_col : ending col of the mark, 0-based exclusive. ---- • hl_group : name of the highlight group used to highlight ---- this mark. ---- • hl_eol : when true, for a multiline highlight covering the ---- EOL of a line, continue the highlight for the rest of the ---- screen line (just like for diff and cursorline highlight). ---- • virt_text : virtual text to link to this mark. A list of ---- [text, highlight] tuples, each representing a text chunk ---- with specified highlight. `highlight` element can either ---- be a single highlight group, or an array of multiple ---- highlight groups that will be stacked (highest priority ---- last). A highlight group can be supplied either as a ---- string or as an integer, the latter which can be obtained ---- using `nvim_get_hl_id_by_name()`. ---- • virt_text_pos : position of virtual text. Possible values: ---- • "eol": right after eol character (default). ---- • "overlay": display over the specified column, without ---- shifting the underlying text. ---- • "right_align": display right aligned in the window. ---- • "inline": display at the specified column, and shift the ---- buffer text to the right as needed. ---- ---- • virt_text_win_col : position the virtual text at a fixed ---- window column (starting from the first text column of the ---- screen line) instead of "virt_text_pos". ---- • virt_text_hide : hide the virtual text when the background ---- text is selected or hidden because of scrolling with ---- 'nowrap' or 'smoothscroll'. Currently only affects ---- "overlay" virt_text. ---- • virt_text_repeat_linebreak : repeat the virtual text on ---- wrapped lines. ---- • hl_mode : control how highlights are combined with the ---- highlights of the text. Currently only affects virt_text ---- highlights, but might affect `hl_group` in ---- later versions. ---- • "replace": only show the virt_text color. This is the ---- default. ---- • "combine": combine with background text color. ---- • "blend": blend with background text color. Not supported ---- for "inline" virt_text. ---- ---- • virt_lines : virtual lines to add next to this mark This ---- should be an array over lines, where each line in turn is ---- an array over [text, highlight] tuples. In general, buffer ---- and window options do not affect the display of the text. ---- In particular 'wrap' and 'linebreak' options do not take ---- effect, so the number of extra screen lines will always ---- match the size of the array. However the 'tabstop' buffer ---- option is still used for hard tabs. By default lines are ---- placed below the buffer line containing the mark. ---- • virt_lines_above: place virtual lines above instead. ---- • virt_lines_leftcol: Place extmarks in the leftmost column ---- of the window, bypassing sign and number columns. ---- • ephemeral : for use with `nvim_set_decoration_provider()` ---- callbacks. The mark will only be used for the current ---- redraw cycle, and not be permantently stored in the ---- buffer. ---- • right_gravity : boolean that indicates the direction the ---- extmark will be shifted in when new text is inserted (true ---- for right, false for left). Defaults to true. ---- • end_right_gravity : boolean that indicates the direction ---- the extmark end position (if it exists) will be shifted in ---- when new text is inserted (true for right, false for ---- left). Defaults to false. ---- • undo_restore : Restore the exact position of the mark if ---- text around the mark was deleted and then restored by ---- undo. Defaults to true. ---- • invalidate : boolean that indicates whether to hide the ---- extmark if the entirety of its range is deleted. For ---- hidden marks, an "invalid" key is added to the "details" ---- array of `nvim_buf_get_extmarks()` and family. If ---- "undo_restore" is false, the extmark is deleted instead. ---- • priority: a priority value for the highlight group, sign ---- attribute or virtual text. For virtual text, item with ---- highest priority is drawn last. For example treesitter ---- highlighting uses a value of 100. ---- • strict: boolean that indicates extmark should not be ---- placed if the line or column value is past the end of the ---- buffer or end of the line respectively. Defaults to true. ---- • sign_text: string of length 1-2 used to display in the ---- sign column. ---- • sign_hl_group: name of the highlight group used to ---- highlight the sign column text. ---- • number_hl_group: name of the highlight group used to ---- highlight the number column. ---- • line_hl_group: name of the highlight group used to ---- highlight the whole line. ---- • cursorline_hl_group: name of the highlight group used to ---- highlight the sign column text when the cursor is on the ---- same line as the mark and 'cursorline' is enabled. ---- • conceal: string which should be either empty or a single ---- character. Enable concealing similar to `:syn-conceal`. ---- When a character is supplied it is used as `:syn-cchar`. ---- "hl_group" is used as highlight for the cchar if provided, ---- otherwise it defaults to `hl-Conceal`. ---- • spell: boolean indicating that spell checking should be ---- performed within this extmark ---- • ui_watched: boolean that indicates the mark should be ---- drawn by a UI. When set, the UI will receive win_extmark ---- events. Note: the mark is positioned by virt_text ---- attributes. Can be used together with virt_text. ---- • url: A URL to associate with this extmark. In the TUI, the ---- OSC 8 control sequence is used to generate a clickable ---- hyperlink to this URL. ---- • scoped: boolean that indicates that the extmark should ---- only be displayed in the namespace scope. (experimental) +--- • id : id of the extmark to edit. +--- • end_row : ending line of the mark, 0-based inclusive. +--- • end_col : ending col of the mark, 0-based exclusive. +--- • hl_group : name of the highlight group used to highlight +--- this mark. +--- • hl_eol : when true, for a multiline highlight covering the +--- EOL of a line, continue the highlight for the rest of the +--- screen line (just like for diff and cursorline highlight). +--- • virt_text : virtual text to link to this mark. A list of +--- [text, highlight] tuples, each representing a text chunk +--- with specified highlight. `highlight` element can either be +--- a single highlight group, or an array of multiple highlight +--- groups that will be stacked (highest priority last). A +--- highlight group can be supplied either as a string or as an +--- integer, the latter which can be obtained using +--- `nvim_get_hl_id_by_name()`. +--- • virt_text_pos : position of virtual text. Possible values: +--- • "eol": right after eol character (default). +--- • "overlay": display over the specified column, without +--- shifting the underlying text. +--- • "right_align": display right aligned in the window. +--- • "inline": display at the specified column, and shift the +--- buffer text to the right as needed. +--- • virt_text_win_col : position the virtual text at a fixed +--- window column (starting from the first text column of the +--- screen line) instead of "virt_text_pos". +--- • virt_text_hide : hide the virtual text when the background +--- text is selected or hidden because of scrolling with +--- 'nowrap' or 'smoothscroll'. Currently only affects "overlay" +--- virt_text. +--- • virt_text_repeat_linebreak : repeat the virtual text on +--- wrapped lines. +--- • hl_mode : control how highlights are combined with the +--- highlights of the text. Currently only affects virt_text +--- highlights, but might affect `hl_group` in later versions. +--- • "replace": only show the virt_text color. This is the +--- default. +--- • "combine": combine with background text color. +--- • "blend": blend with background text color. Not supported +--- for "inline" virt_text. +--- • virt_lines : virtual lines to add next to this mark This +--- should be an array over lines, where each line in turn is an +--- array over [text, highlight] tuples. In general, buffer and +--- window options do not affect the display of the text. In +--- particular 'wrap' and 'linebreak' options do not take +--- effect, so the number of extra screen lines will always +--- match the size of the array. However the 'tabstop' buffer +--- option is still used for hard tabs. By default lines are +--- placed below the buffer line containing the mark. +--- • virt_lines_above: place virtual lines above instead. +--- • virt_lines_leftcol: Place extmarks in the leftmost column of +--- the window, bypassing sign and number columns. +--- • ephemeral : for use with `nvim_set_decoration_provider()` +--- callbacks. The mark will only be used for the current redraw +--- cycle, and not be permantently stored in the buffer. +--- • right_gravity : boolean that indicates the direction the +--- extmark will be shifted in when new text is inserted (true +--- for right, false for left). Defaults to true. +--- • end_right_gravity : boolean that indicates the direction the +--- extmark end position (if it exists) will be shifted in when +--- new text is inserted (true for right, false for left). +--- Defaults to false. +--- • undo_restore : Restore the exact position of the mark if +--- text around the mark was deleted and then restored by undo. +--- Defaults to true. +--- • invalidate : boolean that indicates whether to hide the +--- extmark if the entirety of its range is deleted. For hidden +--- marks, an "invalid" key is added to the "details" array of +--- `nvim_buf_get_extmarks()` and family. If "undo_restore" is +--- false, the extmark is deleted instead. +--- • priority: a priority value for the highlight group, sign +--- attribute or virtual text. For virtual text, item with +--- highest priority is drawn last. For example treesitter +--- highlighting uses a value of 100. +--- • strict: boolean that indicates extmark should not be placed +--- if the line or column value is past the end of the buffer or +--- end of the line respectively. Defaults to true. +--- • sign_text: string of length 1-2 used to display in the sign +--- column. +--- • sign_hl_group: name of the highlight group used to highlight +--- the sign column text. +--- • number_hl_group: name of the highlight group used to +--- highlight the number column. +--- • line_hl_group: name of the highlight group used to highlight +--- the whole line. +--- • cursorline_hl_group: name of the highlight group used to +--- highlight the sign column text when the cursor is on the +--- same line as the mark and 'cursorline' is enabled. +--- • conceal: string which should be either empty or a single +--- character. Enable concealing similar to `:syn-conceal`. When +--- a character is supplied it is used as `:syn-cchar`. +--- "hl_group" is used as highlight for the cchar if provided, +--- otherwise it defaults to `hl-Conceal`. +--- • spell: boolean indicating that spell checking should be +--- performed within this extmark +--- • ui_watched: boolean that indicates the mark should be drawn +--- by a UI. When set, the UI will receive win_extmark events. +--- Note: the mark is positioned by virt_text attributes. Can be +--- used together with virt_text. +--- • url: A URL to associate with this extmark. In the TUI, the +--- OSC 8 control sequence is used to generate a clickable +--- hyperlink to this URL. +--- • scoped: boolean that indicates that the extmark should only +--- be displayed in the namespace scope. (experimental) --- @return integer function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end @@ -623,11 +638,14 @@ function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end function vim.api.nvim_buf_set_keymap(buffer, mode, lhs, rhs, opts) end --- Sets (replaces) a line-range in the buffer. +--- --- Indexing is zero-based, end-exclusive. Negative indices are interpreted as --- length+1+index: -1 refers to the index past the end. So to change or --- delete the last element use start=-2 and end=-1. +--- --- To insert lines at a given index, set `start` and `end` to the same index. --- To delete a range of lines, set `replacement` to an empty array. +--- --- Out-of-bounds indices are clamped to the nearest valid value, unless --- `strict_indexing` is set. --- @@ -640,6 +658,7 @@ function vim.api.nvim_buf_set_lines(buffer, start, end_, strict_indexing, replac --- Sets a named mark in the given buffer, all marks are allowed --- file/uppercase, visual, last change, etc. See `mark-motions`. +--- --- Marks are (1,0)-indexed. `api-indexing` --- --- @param buffer integer Buffer to set the mark on @@ -663,16 +682,21 @@ function vim.api.nvim_buf_set_name(buffer, name) end function vim.api.nvim_buf_set_option(buffer, name, value) end --- Sets (replaces) a range in the buffer +--- --- This is recommended over `nvim_buf_set_lines()` when only modifying parts --- of a line, as extmarks will be preserved on non-modified parts of the --- touched lines. +--- --- Indexing is zero-based. Row indices are end-inclusive, and column indices --- are end-exclusive. +--- --- To insert text at a given `(row, column)` location, use `start_row = --- end_row = row` and `start_col = end_col = col`. To delete the text in a --- range, use `replacement = {}`. +--- --- Prefer `nvim_buf_set_lines()` if you are only adding or deleting entire --- lines. +--- --- Prefer `nvim_put()` if you want to insert text at the cursor position. --- --- @param buffer integer Buffer handle, or 0 for current buffer @@ -700,6 +724,7 @@ function vim.api.nvim_buf_set_var(buffer, name, value) end function vim.api.nvim_buf_set_virtual_text(buffer, src_id, line, chunks, opts) end --- Calls a Vimscript `Dictionary-function` with the given arguments. +--- --- On execution error: fails with Vimscript error, updates v:errmsg. --- --- @param dict any Dictionary, or String evaluating to a Vimscript `self` dict @@ -709,6 +734,7 @@ function vim.api.nvim_buf_set_virtual_text(buffer, src_id, line, chunks, opts) e function vim.api.nvim_call_dict_function(dict, fn, args) end --- Calls a Vimscript function with the given arguments. +--- --- On execution error: fails with Vimscript error, updates v:errmsg. --- --- @param fn string Function to call @@ -720,6 +746,7 @@ function vim.api.nvim_call_function(fn, args) end --- process. For the stdio channel `channel-stdio`, it writes to Nvim's --- stdout. For an internal terminal instance (`nvim_open_term()`) it writes --- directly to terminal output. See `channel-bytes` for more information. +--- --- This function writes raw data, not RPC messages. If the channel was --- created with `rpc=true` then the channel expects RPC messages, use --- `vim.rpcnotify()` and `vim.rpcrequest()` instead. @@ -736,42 +763,41 @@ function vim.api.nvim_chan_send(chan, data) end --- • event: "pat1" --- • event: { "pat1" } --- • event: { "pat1", "pat2", "pat3" } ---- --- • pattern: (string|table) --- • pattern or patterns to match exactly. --- • For example, if you have `*.py` as that pattern for the --- autocmd, you must pass `*.py` exactly to clear it. --- `test.py` will not match the pattern. ---- --- • defaults to clearing all patterns. --- • NOTE: Cannot be used with {buffer} ---- --- • buffer: (bufnr) --- • clear only `autocmd-buflocal` autocommands. --- • NOTE: Cannot be used with {pattern} ---- --- • group: (string|int) The augroup name or id. --- • NOTE: If not passed, will only delete autocmds not in any --- group. function vim.api.nvim_clear_autocmds(opts) end --- Executes an Ex command. +--- --- Unlike `nvim_command()` this command takes a structured Dictionary instead --- of a String. This allows for easier construction and manipulation of an Ex --- command. This also allows for things such as having spaces inside a --- command argument, expanding filenames in a command that otherwise doesn't --- expand filenames, etc. Command arguments may also be Number, Boolean or --- String. +--- --- The first argument may also be used instead of count for commands that --- support it in order to make their usage simpler with `vim.cmd()`. For --- example, instead of `vim.cmd.bdelete{ count = 2 }`, you may do --- `vim.cmd.bdelete(2)`. +--- --- On execution error: fails with Vimscript error, updates v:errmsg. --- --- @param cmd vim.api.keyset.cmd Command to execute. Must be a Dictionary that can contain the ---- same values as the return value of `nvim_parse_cmd()` except ---- "addr", "nargs" and "nextcmd" which are ignored if provided. ---- All values except for "cmd" are optional. +--- same values as the return value of `nvim_parse_cmd()` except +--- "addr", "nargs" and "nextcmd" which are ignored if provided. +--- All values except for "cmd" are optional. --- @param opts vim.api.keyset.cmd_opts Optional parameters. --- • output: (boolean, default false) Whether to return command --- output. @@ -779,7 +805,9 @@ function vim.api.nvim_clear_autocmds(opts) end function vim.api.nvim_cmd(cmd, opts) end --- Executes an Ex command. +--- --- On execution error: fails with Vimscript error, updates v:errmsg. +--- --- Prefer using `nvim_cmd()` or `nvim_exec2()` over this. To evaluate --- multiple lines of Vim script or an Ex command directly, use --- `nvim_exec2()`. To construct an Ex command using a structured format and @@ -800,11 +828,12 @@ function vim.api.nvim_command_output(command) end --- --- @param index integer the completion candidate index --- @param opts vim.api.keyset.complete_set Optional parameters. ---- • info: (string) info text. +--- • info: (string) info text. --- @return table<string,any> function vim.api.nvim_complete_set(index, opts) end --- Create or get an autocommand group `autocmd-groups`. +--- --- To get an existing group id, do: --- --- ```lua @@ -813,6 +842,7 @@ function vim.api.nvim_complete_set(index, opts) end --- }) --- ``` --- +--- --- @param name string String: The name of the group --- @param opts vim.api.keyset.create_augroup Dictionary Parameters --- • clear (bool) optional: defaults to true. Clear existing @@ -820,8 +850,10 @@ function vim.api.nvim_complete_set(index, opts) end --- @return integer function vim.api.nvim_create_augroup(name, opts) end ---- Creates an `autocommand` event handler, defined by `callback` (Lua function ---- or Vimscript function name string) or `command` (Ex command string). +--- Creates an `autocommand` event handler, defined by `callback` (Lua +--- function or Vimscript function name string) or `command` (Ex command +--- string). +--- --- Example using Lua callback: --- --- ```lua @@ -849,39 +881,39 @@ function vim.api.nvim_create_augroup(name, opts) end --- pattern = vim.fn.expand("~") .. "/some/path/*.py" --- ``` --- +--- --- @param event any (string|array) Event(s) that will trigger the handler --- (`callback` or `command`). --- @param opts vim.api.keyset.create_autocmd Options dict: ---- • group (string|integer) optional: autocommand group name or ---- id to match against. ---- • pattern (string|array) optional: pattern(s) to match ---- literally `autocmd-pattern`. ---- • buffer (integer) optional: buffer number for buffer-local ---- autocommands `autocmd-buflocal`. Cannot be used with ---- {pattern}. ---- • desc (string) optional: description (for documentation and ---- troubleshooting). ---- • callback (function|string) optional: Lua function (or ---- Vimscript function name, if string) called when the ---- event(s) is triggered. Lua callback can return a truthy ---- value (not `false` or `nil`) to delete the ---- autocommand. Receives a table argument with these keys: ---- • id: (number) autocommand id ---- • event: (string) name of the triggered event ---- `autocmd-events` ---- • group: (number|nil) autocommand group id, if any ---- • match: (string) expanded value of `<amatch>` ---- • buf: (number) expanded value of `<abuf>` ---- • file: (string) expanded value of `<afile>` ---- • data: (any) arbitrary data passed from ---- `nvim_exec_autocmds()` ---- ---- • command (string) optional: Vim command to execute on event. ---- Cannot be used with {callback} ---- • once (boolean) optional: defaults to false. Run the ---- autocommand only once `autocmd-once`. ---- • nested (boolean) optional: defaults to false. Run nested ---- autocommands `autocmd-nested`. +--- • group (string|integer) optional: autocommand group name or +--- id to match against. +--- • pattern (string|array) optional: pattern(s) to match +--- literally `autocmd-pattern`. +--- • buffer (integer) optional: buffer number for buffer-local +--- autocommands `autocmd-buflocal`. Cannot be used with +--- {pattern}. +--- • desc (string) optional: description (for documentation and +--- troubleshooting). +--- • callback (function|string) optional: Lua function (or +--- Vimscript function name, if string) called when the event(s) +--- is triggered. Lua callback can return a truthy value (not +--- `false` or `nil`) to delete the autocommand. Receives a +--- table argument with these keys: +--- • id: (number) autocommand id +--- • event: (string) name of the triggered event +--- `autocmd-events` +--- • group: (number|nil) autocommand group id, if any +--- • match: (string) expanded value of `<amatch>` +--- • buf: (number) expanded value of `<abuf>` +--- • file: (string) expanded value of `<afile>` +--- • data: (any) arbitrary data passed from +--- `nvim_exec_autocmds()` +--- • command (string) optional: Vim command to execute on event. +--- Cannot be used with {callback} +--- • once (boolean) optional: defaults to false. Run the +--- autocommand only once `autocmd-once`. +--- • nested (boolean) optional: defaults to false. Run nested +--- autocommands `autocmd-nested`. --- @return integer function vim.api.nvim_create_autocmd(event, opts) end @@ -894,9 +926,11 @@ function vim.api.nvim_create_autocmd(event, opts) end --- @return integer function vim.api.nvim_create_buf(listed, scratch) end ---- Creates a new namespace or gets an existing one. *namespace* +--- Creates a new namespace or gets an existing one. *namespace* +--- --- Namespaces are used for buffer highlights and virtual text, see --- `nvim_buf_add_highlight()` and `nvim_buf_set_extmark()`. +--- --- Namespaces can be named or anonymous. If `name` matches an existing --- namespace, the associated id is returned. If `name` is an empty string a --- new, anonymous namespace is created. @@ -906,7 +940,9 @@ function vim.api.nvim_create_buf(listed, scratch) end function vim.api.nvim_create_namespace(name) end --- Creates a global `user-commands` command. +--- --- For Lua usage see `lua-guide-commands-create`. +--- --- Example: --- --- ```vim @@ -915,8 +951,9 @@ function vim.api.nvim_create_namespace(name) end --- Hello world! --- ``` --- +--- --- @param name string Name of the new user command. Must begin with an uppercase ---- letter. +--- letter. --- @param command any Replacement command to execute when this user command is --- executed. When called from Lua, the command can also be a --- Lua function. The function is called with a single table @@ -943,23 +980,24 @@ function vim.api.nvim_create_namespace(name) end --- Has the same structure as the "mods" key of --- `nvim_parse_cmd()`. --- @param opts vim.api.keyset.user_command Optional `command-attributes`. ---- • Set boolean attributes such as `:command-bang` or ---- `:command-bar` to true (but not `:command-buffer`, use ---- `nvim_buf_create_user_command()` instead). ---- • "complete" `:command-complete` also accepts a Lua ---- function which works like ---- `:command-completion-customlist`. ---- • Other parameters: ---- • desc: (string) Used for listing the command when a Lua ---- function is used for {command}. ---- • force: (boolean, default true) Override any previous ---- definition. ---- • preview: (function) Preview callback for 'inccommand' ---- `:command-preview` +--- • Set boolean attributes such as `:command-bang` or +--- `:command-bar` to true (but not `:command-buffer`, use +--- `nvim_buf_create_user_command()` instead). +--- • "complete" `:command-complete` also accepts a Lua function +--- which works like `:command-completion-customlist`. +--- • Other parameters: +--- • desc: (string) Used for listing the command when a Lua +--- function is used for {command}. +--- • force: (boolean, default true) Override any previous +--- definition. +--- • preview: (function) Preview callback for 'inccommand' +--- `:command-preview` function vim.api.nvim_create_user_command(name, command, opts) end --- Delete an autocommand group by id. +--- --- To get a group id one can use `nvim_get_autocmds()`. +--- --- NOTE: behavior differs from `:augroup-delete`. When deleting a group, --- autocommands contained in this group will also be deleted and cleared. --- This group will no longer exist. @@ -968,6 +1006,7 @@ function vim.api.nvim_create_user_command(name, command, opts) end function vim.api.nvim_del_augroup_by_id(id) end --- Delete an autocommand group by name. +--- --- NOTE: behavior differs from `:augroup-delete`. When deleting a group, --- autocommands contained in this group will also be deleted and cleared. --- This group will no longer exist. @@ -985,6 +1024,7 @@ function vim.api.nvim_del_autocmd(id) end function vim.api.nvim_del_current_line() end --- Unmaps a global `mapping` for the given mode. +--- --- To unmap a buffer-local mapping, use `nvim_buf_del_keymap()`. --- --- @param mode string @@ -1010,14 +1050,14 @@ function vim.api.nvim_del_var(name) end --- Echo a message. --- --- @param chunks any[] A list of [text, hl_group] arrays, each representing a text ---- chunk with specified highlight. `hl_group` element can be ---- omitted for no highlight. +--- chunk with specified highlight. `hl_group` element can be +--- omitted for no highlight. --- @param history boolean if true, add to `message-history`. --- @param opts vim.api.keyset.echo_opts Optional parameters. ---- • verbose: Message was printed as a result of 'verbose' ---- option if Nvim was invoked with -V3log_file, the message ---- will be redirected to the log_file and suppressed from ---- direct output. +--- • verbose: Message was printed as a result of 'verbose' option +--- if Nvim was invoked with -V3log_file, the message will be +--- redirected to the log_file and suppressed from direct +--- output. function vim.api.nvim_echo(chunks, history, opts) end --- Writes a message to the Vim error buffer. Does not append "\n", the @@ -1034,6 +1074,7 @@ function vim.api.nvim_err_writeln(str) end --- Evaluates a Vimscript `expression`. Dictionaries and Lists are recursively --- expanded. +--- --- On execution error: fails with Vimscript error, updates v:errmsg. --- --- @param expr string Vimscript expression string @@ -1068,8 +1109,10 @@ function vim.api.nvim_exec(src, output) end --- Executes Vimscript (multiline block of Ex commands), like anonymous --- `:source`. +--- --- Unlike `nvim_command()` this function supports heredocs, script-scope --- (s:), etc. +--- --- On execution error: fails with Vimscript error, updates v:errmsg. --- --- @param src string Vimscript code @@ -1084,24 +1127,27 @@ function vim.api.nvim_exec2(src, opts) end --- --- @param event any (String|Array) The event or events to execute --- @param opts vim.api.keyset.exec_autocmds Dictionary of autocommand options: ---- • group (string|integer) optional: the autocommand group name ---- or id to match against. `autocmd-groups`. ---- • pattern (string|array) optional: defaults to "*" ---- `autocmd-pattern`. Cannot be used with {buffer}. ---- • buffer (integer) optional: buffer number ---- `autocmd-buflocal`. Cannot be used with {pattern}. ---- • modeline (bool) optional: defaults to true. Process the ---- modeline after the autocommands `<nomodeline>`. ---- • data (any): arbitrary data to send to the autocommand ---- callback. See `nvim_create_autocmd()` for details. +--- • group (string|integer) optional: the autocommand group name +--- or id to match against. `autocmd-groups`. +--- • pattern (string|array) optional: defaults to "*" +--- `autocmd-pattern`. Cannot be used with {buffer}. +--- • buffer (integer) optional: buffer number `autocmd-buflocal`. +--- Cannot be used with {pattern}. +--- • modeline (bool) optional: defaults to true. Process the +--- modeline after the autocommands `<nomodeline>`. +--- • data (any): arbitrary data to send to the autocommand +--- callback. See `nvim_create_autocmd()` for details. function vim.api.nvim_exec_autocmds(event, opts) end --- Sends input-keys to Nvim, subject to various quirks controlled by `mode` --- flags. This is a blocking call, unlike `nvim_input()`. +--- --- On execution error: does not fail, but updates v:errmsg. +--- --- To input sequences like <C-o> use `nvim_replace_termcodes()` (typically --- with escape_ks=false) to replace `keycodes`, then pass the result to --- nvim_feedkeys(). +--- --- Example: --- --- ```vim @@ -1109,6 +1155,7 @@ function vim.api.nvim_exec_autocmds(event, opts) end --- :call nvim_feedkeys(key, 'n', v:false) --- ``` --- +--- --- @param keys string to be typed --- @param mode string behavior flags, see `feedkeys()` --- @param escape_ks boolean If true, escape K_SPECIAL bytes in `keys`. This should be @@ -1117,6 +1164,7 @@ function vim.api.nvim_exec_autocmds(event, opts) end function vim.api.nvim_feedkeys(keys, mode, escape_ks) end --- Gets the option information for all options. +--- --- The dictionary has the full option names as keys and option metadata --- dictionaries as detailed at `nvim_get_option_info2()`. --- @@ -1124,6 +1172,7 @@ function vim.api.nvim_feedkeys(keys, mode, escape_ks) end function vim.api.nvim_get_all_options_info() end --- Get all autocommands that match the corresponding {opts}. +--- --- These examples will get autocommands matching ALL the given criteria: --- --- ```lua @@ -1164,6 +1213,7 @@ function vim.api.nvim_get_chan_info(chan) end --- Returns the 24-bit RGB value of a `nvim_get_color_map()` color name or --- "#rrggbb" hexadecimal string. +--- --- Example: --- --- ```vim @@ -1171,11 +1221,13 @@ function vim.api.nvim_get_chan_info(chan) end --- :echo nvim_get_color_by_name("#cbcbcb") --- ``` --- +--- --- @param name string Color name or "#rrggbb" string --- @return integer function vim.api.nvim_get_color_by_name(name) end --- Returns a map of color names and RGB values. +--- --- Keys are color names (e.g. "Aqua") and values are 24-bit RGB color values --- (e.g. 65535). --- @@ -1183,6 +1235,7 @@ function vim.api.nvim_get_color_by_name(name) end function vim.api.nvim_get_color_map() end --- Gets a map of global (non-buffer-local) Ex commands. +--- --- Currently only `user-commands` are supported, not builtin Ex commands. --- --- @param opts vim.api.keyset.get_commands Optional parameters. Currently only supports {"builtin":false} @@ -1223,12 +1276,12 @@ function vim.api.nvim_get_current_win() end --- `nvim_get_namespaces()`. Use 0 to get global highlight groups --- `:highlight`. --- @param opts vim.api.keyset.get_highlight Options dict: ---- • name: (string) Get a highlight definition by name. ---- • id: (integer) Get a highlight definition by id. ---- • link: (boolean, default true) Show linked group name ---- instead of effective definition `:hi-link`. ---- • create: (boolean, default true) When highlight group ---- doesn't exist create it. +--- • name: (string) Get a highlight definition by name. +--- • id: (integer) Get a highlight definition by id. +--- • link: (boolean, default true) Show linked group name instead +--- of effective definition `:hi-link`. +--- • create: (boolean, default true) When highlight group doesn't +--- exist create it. --- @return vim.api.keyset.hl_info function vim.api.nvim_get_hl(ns_id, opts) end @@ -1245,6 +1298,7 @@ function vim.api.nvim_get_hl_by_id(hl_id, rgb) end function vim.api.nvim_get_hl_by_name(name, rgb) end --- Gets a highlight group by name +--- --- similar to `hlID()`, but allocates a new ID if not present. --- --- @param name string @@ -1270,6 +1324,7 @@ function vim.api.nvim_get_keymap(mode) end --- Returns a `(row, col, buffer, buffername)` tuple representing the position --- of the uppercase/file named mark. "End of line" column position is --- returned as `v:maxcol` (big number). See `mark-motions`. +--- --- Marks are (1,0)-indexed. `api-indexing` --- --- @param name string Mark name @@ -1299,6 +1354,7 @@ function vim.api.nvim_get_option(name) end function vim.api.nvim_get_option_info(name) end --- Gets the option information for one option from arbitrary buffer or window +--- --- Resulting dictionary has keys: --- • name: Name of the option (like 'filetype') --- • shortname: Shortened name of the option (like 'ft') @@ -1360,10 +1416,12 @@ function vim.api.nvim_get_proc(pid) end function vim.api.nvim_get_proc_children(pid) end --- Find files in runtime directories +--- --- "name" can contain wildcards. For example --- nvim_get_runtime_file("colors/*.vim", true) will return all color scheme --- files. Always use forward slashes (/) in the search pattern for --- subdirectories regardless of platform. +--- --- It is not an error to not find any files. An empty array is returned then. --- --- @param name string pattern of files to search for @@ -1386,6 +1444,7 @@ function vim.api.nvim_get_vvar(name) end --- Queues raw user-input. Unlike `nvim_feedkeys()`, this uses a low-level --- input buffer and the call is non-blocking (input is processed --- asynchronously by the eventloop). +--- --- On execution error: does not fail, but updates v:errmsg. --- --- @param keys string to be typed @@ -1393,14 +1452,15 @@ function vim.api.nvim_get_vvar(name) end function vim.api.nvim_input(keys) end --- Send mouse event from GUI. +--- --- Non-blocking: does not wait on any result, but queues the event to be --- processed soon by the event loop. --- --- @param button string Mouse button: one of "left", "right", "middle", "wheel", ---- "move", "x1", "x2". ---- @param action string For ordinary buttons, one of "press", "drag", "release". ---- For the wheel, one of "up", "down", "left", "right". ---- Ignored for "move". +--- "move", "x1", "x2". +--- @param action string For ordinary buttons, one of "press", "drag", "release". For +--- the wheel, one of "up", "down", "left", "right". Ignored for +--- "move". --- @param modifier string String of modifiers each represented by a single char. The --- same specifiers are used as for a key press, except that --- the "-" separator is optional, so "C-A-", "c-a" and "CA" @@ -1411,6 +1471,7 @@ function vim.api.nvim_input(keys) end function vim.api.nvim_input_mouse(button, action, modifier, grid, row, col) end --- Gets the current list of buffer handles +--- --- Includes unlisted (unloaded/deleted) buffers, like `:ls!`. Use --- `nvim_buf_is_loaded()` to check if a buffer is loaded. --- @@ -1449,6 +1510,7 @@ function vim.api.nvim_list_wins() end function vim.api.nvim_load_context(dict) end --- Notify the user with a message +--- --- Relays the call to vim.notify . By default forwards your message in the --- echo area but can be overridden to trigger desktop notifications. --- @@ -1459,10 +1521,12 @@ function vim.api.nvim_load_context(dict) end function vim.api.nvim_notify(msg, log_level, opts) end --- Open a terminal instance in a buffer +--- --- By default (and currently the only option) the terminal will not be --- connected to an external process. Instead, input send on the channel will --- be echoed directly by the terminal. This is useful to display ANSI --- terminal sequences returned as part of a rpc message, or similar. +--- --- Note: to directly initiate the terminal using the right size, display the --- buffer in a configured window before calling this. For instance, for a --- floating display, first create an empty buffer using `nvim_create_buf()`, @@ -1472,27 +1536,30 @@ function vim.api.nvim_notify(msg, log_level, opts) end --- --- @param buffer integer the buffer to use (expected to be empty) --- @param opts vim.api.keyset.open_term Optional parameters. ---- • on_input: Lua callback for input sent, i e keypresses in ---- terminal mode. Note: keypresses are sent raw as they would ---- be to the pty master end. For instance, a carriage return ---- is sent as a "\r", not as a "\n". `textlock` applies. It ---- is possible to call `nvim_chan_send()` directly in the ---- callback however. ["input", term, bufnr, data] ---- • force_crlf: (boolean, default true) Convert "\n" to ---- "\r\n". +--- • on_input: Lua callback for input sent, i e keypresses in +--- terminal mode. Note: keypresses are sent raw as they would +--- be to the pty master end. For instance, a carriage return is +--- sent as a "\r", not as a "\n". `textlock` applies. It is +--- possible to call `nvim_chan_send()` directly in the callback +--- however. ["input", term, bufnr, data] +--- • force_crlf: (boolean, default true) Convert "\n" to "\r\n". --- @return integer function vim.api.nvim_open_term(buffer, opts) end --- Opens a new split window, or a floating window if `relative` is specified, --- or an external window (managed by the UI) if `external` is specified. +--- --- Floats are windows that are drawn above the split layout, at some anchor --- position in some other window. Floats can be drawn internally or by --- external GUI with the `ui-multigrid` extension. External windows are only --- supported with multigrid GUIs, and are displayed as separate top-level --- windows. +--- --- For a general overview of floats, see `api-floatwin`. +--- --- The `width` and `height` of the new window must be specified when opening --- a floating window, but are optional for normal windows. +--- --- If `relative` and `external` are omitted, a normal "split" window is --- created. The `win` property determines which window will be split. If no --- `win` is provided or `win == 0`, a window will be created adjacent to the @@ -1501,15 +1568,18 @@ function vim.api.nvim_open_term(buffer, opts) end --- control split direction. For `vertical`, the exact direction is determined --- by `'splitright'` and `'splitbelow'`. Split windows cannot have --- `bufpos`/`row`/`col`/`border`/`title`/`footer` properties. +--- --- With relative=editor (row=0,col=0) refers to the top-left corner of the --- screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right --- corner. Fractional values are allowed, but the builtin implementation --- (used by non-multigrid UIs) will always round down to nearest integer. +--- --- Out-of-bounds values, and configurations that make the float not fit --- inside the main editor, are allowed. The builtin implementation truncates --- values so floats are fully within the main screen grid. External GUIs --- could let floats hover outside of the main window like a tooltip, but this --- should not be used to specify arbitrary WM screen positions. +--- --- Example (Lua): window-relative float --- --- ```lua @@ -1533,6 +1603,7 @@ function vim.api.nvim_open_term(buffer, opts) end --- }) --- ``` --- +--- --- @param buffer integer Buffer to display, or 0 for current buffer --- @param enter boolean Enter the window (make it the current window) --- @param config vim.api.keyset.win_config Map defining the window configuration. Keys: @@ -1543,7 +1614,6 @@ function vim.api.nvim_open_term(buffer, opts) end --- window. --- • "cursor" Cursor position in current window. --- • "mouse" Mouse position ---- --- • win: `window-ID` window to split, or relative window when --- creating a float (relative="win"). --- • anchor: Decides which corner of the float to place at @@ -1552,17 +1622,15 @@ function vim.api.nvim_open_term(buffer, opts) end --- • "NE" northeast --- • "SW" southwest --- • "SE" southeast ---- --- • width: Window width (in character cells). Minimum of 1. --- • height: Window height (in character cells). Minimum of 1. --- • bufpos: Places float relative to buffer text (only when --- relative="win"). Takes a tuple of zero-indexed [line, ---- column]. `row` and `col` if given are ---- applied relative to this position, else they default to: +--- column]. `row` and `col` if given are applied relative to +--- this position, else they default to: --- • `row=1` and `col=0` if `anchor` is "NW" or "NE" --- • `row=0` and `col=0` if `anchor` is "SW" or "SE" (thus --- like a tooltip near the buffer text). ---- --- • row: Row position in units of "screen cell height", may be --- fractional. --- • col: Column position in units of "screen cell width", may @@ -1583,7 +1651,6 @@ function vim.api.nvim_open_term(buffer, opts) end --- wildoptions+=pum) The default value for floats are 50. --- In general, values below 100 are recommended, unless --- there is a good reason to overshadow builtin elements. ---- --- • style: (optional) Configure the appearance of the window. --- Currently only supports one value: --- • "minimal" Nvim will display the window with many UI @@ -1596,14 +1663,13 @@ function vim.api.nvim_open_term(buffer, opts) end --- empty. The end-of-buffer region is hidden by setting --- `eob` flag of 'fillchars' to a space char, and clearing --- the `hl-EndOfBuffer` region in 'winhighlight'. ---- --- • border: Style of (optional) window border. This can either --- be a string or an array. The string values are --- • "none": No border (default). --- • "single": A single line box. --- • "double": A double line box. ---- • "rounded": Like "single", but with rounded corners ("╭" ---- etc.). +--- • "rounded": Like "single", but with rounded corners +--- ("╭" etc.). --- • "solid": Adds padding by a single whitespace cell. --- • "shadow": A drop shadow effect by blending with the --- background. @@ -1611,18 +1677,35 @@ function vim.api.nvim_open_term(buffer, opts) end --- any divisor of eight. The array will specify the eight --- chars building up the border in a clockwise fashion --- starting with the top-left corner. As an example, the ---- double box style could be specified as [ "╔", "═" ,"╗", ---- "║", "╝", "═", "╚", "║" ]. If the number of chars are ---- less than eight, they will be repeated. Thus an ASCII ---- border could be specified as [ "/", "-", "\\", "|" ], or ---- all chars the same as [ "x" ]. An empty string can be ---- used to turn off a specific border, for instance, [ "", ---- "", "", ">", "", "", "", "<" ] will only make vertical ---- borders but not horizontal ones. By default, ---- `FloatBorder` highlight is used, which links to ---- `WinSeparator` when not defined. It could also be ---- specified by character: [ ["+", "MyCorner"], ["x", ---- "MyBorder"] ]. +--- double box style could be specified as: +--- ``` +--- [ "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ]. +--- ``` +--- +--- If the number of chars are less than eight, they will be +--- repeated. Thus an ASCII border could be specified as +--- ``` +--- [ "/", "-", \"\\\\\", "|" ], +--- ``` +--- +--- or all chars the same as +--- ``` +--- [ "x" ]. +--- ``` +--- +--- An empty string can be used to turn off a specific border, +--- for instance, +--- ``` +--- [ "", "", "", ">", "", "", "", "<" ] +--- ``` +--- +--- will only make vertical borders but not horizontal ones. +--- By default, `FloatBorder` highlight is used, which links +--- to `WinSeparator` when not defined. It could also be +--- specified by character: +--- ``` +--- [ ["+", "MyCorner"], ["x", "MyBorder"] ]. +--- ``` --- --- • title: Title (optional) in window border, string or list. --- List should consist of `[text, highlight]` tuples. If @@ -1654,6 +1737,7 @@ function vim.api.nvim_open_win(buffer, enter, config) end function vim.api.nvim_out_write(str) end --- Parse command line. +--- --- Doesn't check the validity of command arguments. --- --- @param str string Command line string to parse. Cannot contain "\n". @@ -1665,17 +1749,17 @@ function vim.api.nvim_parse_cmd(str, opts) end --- --- @param expr string Expression to parse. Always treated as a single line. --- @param flags string Flags: ---- • "m" if multiple expressions in a row are allowed (only ---- the first one will be parsed), ---- • "E" if EOC tokens are not allowed (determines whether ---- they will stop parsing process or be recognized as an ---- operator/space, though also yielding an error). ---- • "l" when needing to start parsing with lvalues for ---- ":let" or ":for". Common flag sets: ---- • "m" to parse like for ":echo". ---- • "E" to parse like for "<C-r>=". ---- • empty string for ":call". ---- • "lm" to parse for ":let". +--- • "m" if multiple expressions in a row are allowed (only the +--- first one will be parsed), +--- • "E" if EOC tokens are not allowed (determines whether they +--- will stop parsing process or be recognized as an +--- operator/space, though also yielding an error). +--- • "l" when needing to start parsing with lvalues for ":let" +--- or ":for". Common flag sets: +--- • "m" to parse like for ":echo". +--- • "E" to parse like for "<C-r>=". +--- • empty string for ":call". +--- • "lm" to parse for ":let". --- @param highlight boolean If true, return value will also include "highlight" key --- containing array of 4-tuples (arrays) (Integer, Integer, --- Integer, String), where first three numbers define the @@ -1686,8 +1770,10 @@ function vim.api.nvim_parse_cmd(str, opts) end function vim.api.nvim_parse_expression(expr, flags, highlight) end --- Pastes at cursor, in any mode. +--- --- Invokes the `vim.paste` handler, which handles each mode appropriately. --- Sets redo/undo. Faster than `nvim_input()`. Lines break at LF ("\n"). +--- --- Errors ('nomodifiable', `vim.paste()` failure, …) are reflected in `err` --- but do not affect the return value (which is strictly decided by --- `vim.paste()`). On error, subsequent calls are ignored ("drained") until @@ -1696,8 +1782,8 @@ function vim.api.nvim_parse_expression(expr, flags, highlight) end --- @param data string Multiline input. May be binary (containing NUL bytes). --- @param crlf boolean Also break lines at CR and CRLF. --- @param phase integer -1: paste in a single call (i.e. without streaming). To ---- "stream" a paste, call `nvim_paste` sequentially ---- with these `phase` values: +--- "stream" a paste, call `nvim_paste` sequentially with these +--- `phase` values: --- • 1: starts the paste (exactly once) --- • 2: continues the paste (zero or more times) --- • 3: ends the paste (exactly once) @@ -1705,16 +1791,16 @@ function vim.api.nvim_parse_expression(expr, flags, highlight) end function vim.api.nvim_paste(data, crlf, phase) end --- Puts text at cursor, in any mode. +--- --- Compare `:put` and `p` which are always linewise. --- --- @param lines string[] `readfile()`-style list of lines. `channel-lines` --- @param type string Edit behavior: any `getregtype()` result, or: ---- • "b" `blockwise-visual` mode (may include width, e.g. "b3") ---- • "c" `charwise` mode ---- • "l" `linewise` mode ---- • "" guess by contents, see `setreg()` ---- @param after boolean If true insert after cursor (like `p`), or before (like ---- `P`). +--- • "b" `blockwise-visual` mode (may include width, e.g. "b3") +--- • "c" `charwise` mode +--- • "l" `linewise` mode +--- • "" guess by contents, see `setreg()` +--- @param after boolean If true insert after cursor (like `p`), or before (like `P`). --- @param follow boolean If true place cursor at end of inserted text. function vim.api.nvim_put(lines, type, after, follow) end @@ -1729,14 +1815,15 @@ function vim.api.nvim_put(lines, type, after, follow) end function vim.api.nvim_replace_termcodes(str, from_part, do_lt, special) end --- Selects an item in the completion popup menu. +--- --- If neither `ins-completion` nor `cmdline-completion` popup menu is active --- this API call is silently ignored. Useful for an external UI using --- `ui-popupmenu` to control the popup menu with the mouse. Can also be used --- in a mapping; use <Cmd> `:map-cmd` or a Lua mapping to ensure the mapping --- doesn't end completion mode. --- ---- @param item integer Index (zero-based) of the item to select. Value of -1 ---- selects nothing and restores the original text. +--- @param item integer Index (zero-based) of the item to select. Value of -1 selects +--- nothing and restores the original text. --- @param insert boolean For `ins-completion`, whether the selection should be --- inserted in the buffer. Ignored for `cmdline-completion`. --- @param finish boolean Finish the completion and dismiss the popup menu. Implies @@ -1770,13 +1857,16 @@ function vim.api.nvim_set_current_tabpage(tabpage) end function vim.api.nvim_set_current_win(window) end --- Set or change decoration provider for a `namespace` +--- --- This is a very general purpose interface for having Lua callbacks being --- triggered during the redraw code. +--- --- The expected usage is to set `extmarks` for the currently redrawn buffer. --- `nvim_buf_set_extmark()` can be called to add marks on a per-window or --- per-lines basis. Use the `ephemeral` key to only use the mark for the --- current screen redraw (the callback will be called again for the next --- redraw). +--- --- Note: this function should not be called often. Rather, the callbacks --- themselves can be used to throttle unneeded callbacks. the `on_start` --- callback can return `false` to disable the provider until the next redraw. @@ -1785,26 +1875,27 @@ function vim.api.nvim_set_current_win(window) end --- plugin managing multiple sources of decoration should ideally only set one --- provider, and merge the sources internally. You can use multiple `ns_id` --- for the extmarks set/modified inside the callback anyway. +--- --- Note: doing anything other than setting extmarks is considered --- experimental. Doing things like changing options are not explicitly --- forbidden, but is likely to have unexpected consequences (such as 100% CPU --- consumption). doing `vim.rpcnotify` should be OK, but `vim.rpcrequest` is --- quite dubious for the moment. +--- --- Note: It is not allowed to remove or update extmarks in 'on_line' --- callbacks. --- --- @param ns_id integer Namespace id from `nvim_create_namespace()` --- @param opts vim.api.keyset.set_decoration_provider Table of callbacks: ---- • on_start: called first on each screen redraw ["start", ---- tick] ---- • on_buf: called for each buffer being redrawn (before window ---- callbacks) ["buf", bufnr, tick] ---- • on_win: called when starting to redraw a specific window. ---- ["win", winid, bufnr, topline, botline] ---- • on_line: called for each buffer line being redrawn. (The ---- interaction with fold lines is subject to change) ["line", ---- winid, bufnr, row] ---- • on_end: called at the end of a redraw cycle ["end", tick] +--- • on_start: called first on each screen redraw ["start", tick] +--- • on_buf: called for each buffer being redrawn (before window +--- callbacks) ["buf", bufnr, tick] +--- • on_win: called when starting to redraw a specific window. +--- ["win", winid, bufnr, topline, botline] +--- • on_line: called for each buffer line being redrawn. (The +--- interaction with fold lines is subject to change) ["line", +--- winid, bufnr, row] +--- • on_end: called at the end of a redraw cycle ["end", tick] function vim.api.nvim_set_decoration_provider(ns_id, opts) end --- Sets a highlight group. @@ -1816,31 +1907,31 @@ function vim.api.nvim_set_decoration_provider(ns_id, opts) end --- activate them. --- @param name string Highlight group name, e.g. "ErrorMsg" --- @param val vim.api.keyset.highlight Highlight definition map, accepts the following keys: ---- • fg: color name or "#RRGGBB", see note. ---- • bg: color name or "#RRGGBB", see note. ---- • sp: color name or "#RRGGBB" ---- • blend: integer between 0 and 100 ---- • bold: boolean ---- • standout: boolean ---- • underline: boolean ---- • undercurl: boolean ---- • underdouble: boolean ---- • underdotted: boolean ---- • underdashed: boolean ---- • strikethrough: boolean ---- • italic: boolean ---- • reverse: boolean ---- • nocombine: boolean ---- • link: name of another highlight group to link to, see ---- `:hi-link`. ---- • default: Don't override existing definition `:hi-default` ---- • ctermfg: Sets foreground of cterm color `ctermfg` ---- • ctermbg: Sets background of cterm color `ctermbg` ---- • cterm: cterm attribute map, like `highlight-args`. If not ---- set, cterm attributes will match those from the attribute ---- map documented above. ---- • force: if true force update the highlight group when it ---- exists. +--- • fg: color name or "#RRGGBB", see note. +--- • bg: color name or "#RRGGBB", see note. +--- • sp: color name or "#RRGGBB" +--- • blend: integer between 0 and 100 +--- • bold: boolean +--- • standout: boolean +--- • underline: boolean +--- • undercurl: boolean +--- • underdouble: boolean +--- • underdotted: boolean +--- • underdashed: boolean +--- • strikethrough: boolean +--- • italic: boolean +--- • reverse: boolean +--- • nocombine: boolean +--- • link: name of another highlight group to link to, see +--- `:hi-link`. +--- • default: Don't override existing definition `:hi-default` +--- • ctermfg: Sets foreground of cterm color `ctermfg` +--- • ctermbg: Sets background of cterm color `ctermbg` +--- • cterm: cterm attribute map, like `highlight-args`. If not +--- set, cterm attributes will match those from the attribute map +--- documented above. +--- • force: if true force update the highlight group when it +--- exists. function vim.api.nvim_set_hl(ns_id, name, val) end --- Set active namespace for highlights defined with `nvim_set_hl()`. This can @@ -1851,6 +1942,7 @@ function vim.api.nvim_set_hl_ns(ns_id) end --- Set active namespace for highlights defined with `nvim_set_hl()` while --- redrawing. +--- --- This function meant to be called while redrawing, primarily from --- `nvim_set_decoration_provider()` on_win and on_line callbacks, which are --- allowed to change the namespace during a redraw cycle. @@ -1859,9 +1951,12 @@ function vim.api.nvim_set_hl_ns(ns_id) end function vim.api.nvim_set_hl_ns_fast(ns_id) end --- Sets a global `mapping` for the given mode. +--- --- To set a buffer-local mapping, use `nvim_buf_set_keymap()`. +--- --- Unlike `:map`, leading/trailing whitespace is accepted as part of the --- {lhs} or {rhs}. Empty {rhs} is `<Nop>`. `keycodes` are replaced as usual. +--- --- Example: --- --- ```vim @@ -1874,8 +1969,9 @@ function vim.api.nvim_set_hl_ns_fast(ns_id) end --- nmap <nowait> <Space><NL> <Nop> --- ``` --- ---- @param mode string Mode short-name (map command prefix: "n", "i", "v", "x", …) or ---- "!" for `:map!`, or empty string for `:map`. "ia", "ca" or +--- +--- @param mode string Mode short-name (map command prefix: "n", "i", "v", "x", …) +--- or "!" for `:map!`, or empty string for `:map`. "ia", "ca" or --- "!a" for abbreviation in Insert mode, Cmdline mode, or both, --- respectively --- @param lhs string Left-hand-side `{lhs}` of the mapping. @@ -1899,15 +1995,16 @@ function vim.api.nvim_set_option(name, value) end --- Sets the value of an option. The behavior of this function matches that of --- `:set`: for global-local options, both the global and local value are set --- unless otherwise specified with {scope}. +--- --- Note the options {win} and {buf} cannot be used together. --- --- @param name string Option name --- @param value any New option value --- @param opts vim.api.keyset.option Optional parameters ---- • scope: One of "global" or "local". Analogous to ---- `:setglobal` and `:setlocal`, respectively. ---- • win: `window-ID`. Used for setting window local option. ---- • buf: Buffer number. Used for setting buffer local option. +--- • scope: One of "global" or "local". Analogous to `:setglobal` +--- and `:setlocal`, respectively. +--- • win: `window-ID`. Used for setting window local option. +--- • buf: Buffer number. Used for setting buffer local option. function vim.api.nvim_set_option_value(name, value, opts) end --- Sets a global (g:) variable. @@ -1990,7 +2087,7 @@ function vim.api.nvim_win_add_ns(window, ns_id) end --- --- @param window integer Window handle, or 0 for current window --- @param fun function Function to call inside the window (currently Lua callable ---- only) +--- only) --- @return any function vim.api.nvim_win_call(window, fun) end @@ -1998,8 +2095,8 @@ function vim.api.nvim_win_call(window, fun) end --- --- @param window integer Window handle, or 0 for current window --- @param force boolean Behave like `:close!` The last window of a buffer with ---- unwritten changes can be closed. The buffer will become ---- hidden, even if 'hidden' is not set. +--- unwritten changes can be closed. The buffer will become +--- hidden, even if 'hidden' is not set. function vim.api.nvim_win_close(window, force) end --- Removes a window-scoped (w:) variable @@ -2015,7 +2112,9 @@ function vim.api.nvim_win_del_var(window, name) end function vim.api.nvim_win_get_buf(window) end --- Gets window configuration. +--- --- The returned value may be given to `nvim_open_win()`. +--- --- `relative` is empty for normal windows. --- --- @param window integer Window handle, or 0 for current window @@ -2081,6 +2180,7 @@ function vim.api.nvim_win_get_width(window) end --- Closes the window and hide the buffer it contains (like `:hide` with a --- `window-ID`). +--- --- Like `:hide` the buffer becomes hidden unless another window is editing --- it, or 'bufhidden' is `unload`, `delete` or `wipe` as opposed to `:close` --- or `nvim_win_close()`, which will close the buffer. @@ -2109,6 +2209,7 @@ function vim.api.nvim_win_set_buf(window, buffer) end --- Configures window layout. Currently only for floating and external windows --- (including changing a split window to those layouts). +--- --- When reconfiguring a floating window, absent option keys will not be --- changed. `row`/`col` and `relative` must be reconfigured together. --- @@ -2132,6 +2233,7 @@ function vim.api.nvim_win_set_height(window, height) end --- Set highlight namespace for a window. This will use highlights defined --- with `nvim_set_hl()` for this namespace, but fall back to global --- highlights (ns=0) when missing. +--- --- This takes precedence over the 'winhighlight' option. --- --- @param window integer @@ -2160,23 +2262,26 @@ function vim.api.nvim_win_set_width(window, width) end --- Computes the number of screen lines occupied by a range of text in a given --- window. Works for off-screen text and takes folds into account. +--- --- Diff filler or virtual lines above a line are counted as a part of that --- line, unless the line is on "start_row" and "start_vcol" is specified. +--- --- Diff filler or virtual lines below the last buffer line are counted in the --- result when "end_row" is omitted. +--- --- Line indexing is similar to `nvim_buf_get_text()`. --- --- @param window integer Window handle, or 0 for current window. --- @param opts vim.api.keyset.win_text_height Optional parameters: ---- • start_row: Starting line index, 0-based inclusive. When ---- omitted start at the very top. ---- • end_row: Ending line index, 0-based inclusive. When ---- omitted end at the very bottom. ---- • start_vcol: Starting virtual column index on "start_row", ---- 0-based inclusive, rounded down to full screen lines. When ---- omitted include the whole line. ---- • end_vcol: Ending virtual column index on "end_row", ---- 0-based exclusive, rounded up to full screen lines. When ---- omitted include the whole line. +--- • start_row: Starting line index, 0-based inclusive. When +--- omitted start at the very top. +--- • end_row: Ending line index, 0-based inclusive. When omitted +--- end at the very bottom. +--- • start_vcol: Starting virtual column index on "start_row", +--- 0-based inclusive, rounded down to full screen lines. When +--- omitted include the whole line. +--- • end_vcol: Ending virtual column index on "end_row", 0-based +--- exclusive, rounded up to full screen lines. When omitted +--- include the whole line. --- @return table<string,any> function vim.api.nvim_win_text_height(window, opts) end diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua index a422a65792..472162ecc1 100644 --- a/runtime/lua/vim/_meta/builtin.lua +++ b/runtime/lua/vim/_meta/builtin.lua @@ -3,65 +3,63 @@ error('Cannot require a meta file') ----@defgroup vim.builtin ---- ----@brief <pre>help ----vim.api.{func}({...}) *vim.api* ---- Invokes Nvim |API| function {func} with arguments {...}. ---- Example: call the "nvim_get_current_line()" API function: >lua ---- print(tostring(vim.api.nvim_get_current_line())) ---- ----vim.NIL *vim.NIL* ---- Special value representing NIL in |RPC| and |v:null| in Vimscript ---- conversion, and similar cases. Lua `nil` cannot be used as part of a Lua ---- table representing a Dictionary or Array, because it is treated as ---- missing: `{"foo", nil}` is the same as `{"foo"}`. ---- ----vim.type_idx *vim.type_idx* ---- Type index for use in |lua-special-tbl|. Specifying one of the values from ---- |vim.types| allows typing the empty table (it is unclear whether empty Lua ---- table represents empty list or empty array) and forcing integral numbers ---- to be |Float|. See |lua-special-tbl| for more details. ---- ----vim.val_idx *vim.val_idx* ---- Value index for tables representing |Float|s. A table representing ---- floating-point value 1.0 looks like this: >lua ---- { ---- [vim.type_idx] = vim.types.float, ---- [vim.val_idx] = 1.0, ---- } ----< See also |vim.type_idx| and |lua-special-tbl|. ---- ----vim.types *vim.types* ---- Table with possible values for |vim.type_idx|. Contains two sets of ---- key-value pairs: first maps possible values for |vim.type_idx| to ---- human-readable strings, second maps human-readable type names to values ---- for |vim.type_idx|. Currently contains pairs for `float`, `array` and ---- `dictionary` types. ---- ---- Note: One must expect that values corresponding to `vim.types.float`, ---- `vim.types.array` and `vim.types.dictionary` fall under only two following ---- assumptions: ---- 1. Value may serve both as a key and as a value in a table. Given the ---- properties of Lua tables this basically means “value is not `nil`”. ---- 2. For each value in `vim.types` table `vim.types[vim.types[value]]` is the ---- same as `value`. ---- No other restrictions are put on types, and it is not guaranteed that ---- values corresponding to `vim.types.float`, `vim.types.array` and ---- `vim.types.dictionary` will not change or that `vim.types` table will only ---- contain values for these three types. ---- ---- *log_levels* *vim.log.levels* ----Log levels are one of the values defined in `vim.log.levels`: ---- ---- vim.log.levels.DEBUG ---- vim.log.levels.ERROR ---- vim.log.levels.INFO ---- vim.log.levels.TRACE ---- vim.log.levels.WARN ---- vim.log.levels.OFF ---- ----</pre> +--- @brief <pre>help +--- vim.api.{func}({...}) *vim.api* +--- Invokes Nvim |API| function {func} with arguments {...}. +--- Example: call the "nvim_get_current_line()" API function: >lua +--- print(tostring(vim.api.nvim_get_current_line())) +--- +--- vim.NIL *vim.NIL* +--- Special value representing NIL in |RPC| and |v:null| in Vimscript +--- conversion, and similar cases. Lua `nil` cannot be used as part of a Lua +--- table representing a Dictionary or Array, because it is treated as +--- missing: `{"foo", nil}` is the same as `{"foo"}`. +--- +--- vim.type_idx *vim.type_idx* +--- Type index for use in |lua-special-tbl|. Specifying one of the values from +--- |vim.types| allows typing the empty table (it is unclear whether empty Lua +--- table represents empty list or empty array) and forcing integral numbers +--- to be |Float|. See |lua-special-tbl| for more details. +--- +--- vim.val_idx *vim.val_idx* +--- Value index for tables representing |Float|s. A table representing +--- floating-point value 1.0 looks like this: >lua +--- { +--- [vim.type_idx] = vim.types.float, +--- [vim.val_idx] = 1.0, +--- } +--- < See also |vim.type_idx| and |lua-special-tbl|. +--- +--- vim.types *vim.types* +--- Table with possible values for |vim.type_idx|. Contains two sets of +--- key-value pairs: first maps possible values for |vim.type_idx| to +--- human-readable strings, second maps human-readable type names to values +--- for |vim.type_idx|. Currently contains pairs for `float`, `array` and +--- `dictionary` types. +--- +--- Note: One must expect that values corresponding to `vim.types.float`, +--- `vim.types.array` and `vim.types.dictionary` fall under only two following +--- assumptions: +--- 1. Value may serve both as a key and as a value in a table. Given the +--- properties of Lua tables this basically means “value is not `nil`”. +--- 2. For each value in `vim.types` table `vim.types[vim.types[value]]` is the +--- same as `value`. +--- No other restrictions are put on types, and it is not guaranteed that +--- values corresponding to `vim.types.float`, `vim.types.array` and +--- `vim.types.dictionary` will not change or that `vim.types` table will only +--- contain values for these three types. +--- +--- *log_levels* *vim.log.levels* +--- Log levels are one of the values defined in `vim.log.levels`: +--- +--- vim.log.levels.DEBUG +--- vim.log.levels.ERROR +--- vim.log.levels.INFO +--- vim.log.levels.TRACE +--- vim.log.levels.WARN +--- vim.log.levels.OFF +--- +--- </pre> ---@class vim.NIL diff --git a/runtime/lua/vim/_meta/json.lua b/runtime/lua/vim/_meta/json.lua index e010086615..07d89aafc8 100644 --- a/runtime/lua/vim/_meta/json.lua +++ b/runtime/lua/vim/_meta/json.lua @@ -5,7 +5,7 @@ vim.json = {} -- luacheck: no unused args ----@defgroup vim.json +---@brief --- --- This module provides encoding and decoding of Lua objects to and --- from JSON-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. diff --git a/runtime/lua/vim/_meta/lpeg.lua b/runtime/lua/vim/_meta/lpeg.lua index 5bd502a7c8..f2239e5e5a 100644 --- a/runtime/lua/vim/_meta/lpeg.lua +++ b/runtime/lua/vim/_meta/lpeg.lua @@ -5,22 +5,20 @@ error('Cannot require a meta file') -- (based on revision 4aded588f9531d89555566bb1de27490354b91c7) -- with types being renamed to include the vim namespace and with some descriptions made less verbose. ----@defgroup vim.lpeg ----<pre>help ----LPeg is a pattern-matching library for Lua, based on ----Parsing Expression Grammars (https://bford.info/packrat/) (PEGs). +--- @brief <pre>help +--- LPeg is a pattern-matching library for Lua, based on +--- Parsing Expression Grammars (https://bford.info/packrat/) (PEGs). --- ---- *lua-lpeg* ---- *vim.lpeg.Pattern* ----The LPeg library for parsing expression grammars is included as `vim.lpeg` ----(https://www.inf.puc-rio.br/~roberto/lpeg/). +--- *lua-lpeg* +--- *vim.lpeg.Pattern* +--- The LPeg library for parsing expression grammars is included as `vim.lpeg` +--- (https://www.inf.puc-rio.br/~roberto/lpeg/). --- ----In addition, its regex-like interface is available as |vim.re| ----(https://www.inf.puc-rio.br/~roberto/lpeg/re.html). +--- In addition, its regex-like interface is available as |vim.re| +--- (https://www.inf.puc-rio.br/~roberto/lpeg/re.html). --- ----</pre> +--- </pre> ---- *LPeg* is a new pattern-matching library for Lua, based on [Parsing Expression Grammars](https://bford.info/packrat/) (PEGs). vim.lpeg = {} --- @class vim.lpeg.Pattern @@ -88,6 +86,7 @@ function Pattern:match(subject, init) end --- Returns the string `"pattern"` if the given value is a pattern, otherwise `nil`. --- +--- @param value vim.lpeg.Pattern|string|integer|boolean|table|function --- @return "pattern"|nil function vim.lpeg.type(value) end diff --git a/runtime/lua/vim/_meta/mpack.lua b/runtime/lua/vim/_meta/mpack.lua index 54e097ad97..3970341b78 100644 --- a/runtime/lua/vim/_meta/mpack.lua +++ b/runtime/lua/vim/_meta/mpack.lua @@ -2,14 +2,17 @@ -- luacheck: no unused args ---- @defgroup vim.mpack +--- @brief --- --- This module provides encoding and decoding of Lua objects to and --- from msgpack-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. --- Decodes (or "unpacks") the msgpack-encoded {str} to a Lua object. --- @param str string +--- @return any function vim.mpack.decode(str) end --- Encodes (or "packs") Lua object {obj} as msgpack in a Lua string. +--- @param obj any +--- @return string function vim.mpack.encode(obj) end diff --git a/runtime/lua/vim/_meta/re.lua b/runtime/lua/vim/_meta/re.lua index 4f254b19a0..14c94c7824 100644 --- a/runtime/lua/vim/_meta/re.lua +++ b/runtime/lua/vim/_meta/re.lua @@ -7,15 +7,12 @@ error('Cannot require a meta file') -- Copyright © 2007-2023 Lua.org, PUC-Rio. -- See 'lpeg.html' for license ---- @defgroup vim.re ----<pre>help ----The `vim.re` module provides a conventional regex-like syntax for pattern usage ----within LPeg |vim.lpeg|. +--- @brief +--- The `vim.re` module provides a conventional regex-like syntax for pattern usage +--- within LPeg |vim.lpeg|. --- ----See https://www.inf.puc-rio.br/~roberto/lpeg/re.html for the original ----documentation including regex syntax and more concrete examples. ---- ----</pre> +--- See https://www.inf.puc-rio.br/~roberto/lpeg/re.html for the original +--- documentation including regex syntax and more concrete examples. --- Compiles the given {string} and returns an equivalent LPeg pattern. The given string may define --- either an expression or a grammar. The optional {defs} table provides extra Lua values to be used diff --git a/runtime/lua/vim/_meta/regex.lua b/runtime/lua/vim/_meta/regex.lua index 58aa2be8c2..ab403b97e7 100644 --- a/runtime/lua/vim/_meta/regex.lua +++ b/runtime/lua/vim/_meta/regex.lua @@ -2,8 +2,6 @@ -- luacheck: no unused args ---- @defgroup vim.regex ---- --- @brief Vim regexes can be used directly from Lua. Currently they only allow --- matching within a single line. diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua index b83a8dd4b1..f1fed50c6d 100644 --- a/runtime/lua/vim/_options.lua +++ b/runtime/lua/vim/_options.lua @@ -1,12 +1,10 @@ ----@defgroup lua-vimscript +--- @brief Nvim Lua provides an interface or "bridge" to Vimscript variables and +--- functions, and editor commands and options. --- ----@brief Nvim Lua provides an interface or "bridge" to Vimscript variables and ----functions, and editor commands and options. ---- ----Objects passed over this bridge are COPIED (marshalled): there are no ----"references". |lua-guide-variables| For example, using \`vim.fn.remove()\` on ----a Lua list copies the list object to Vimscript and does NOT modify the Lua ----list: +--- Objects passed over this bridge are COPIED (marshalled): there are no +--- "references". |lua-guide-variables| For example, using `vim.fn.remove()` on +--- a Lua list copies the list object to Vimscript and does NOT modify the Lua +--- list: --- --- ```lua --- local list = { 1, 2, 3 } @@ -14,86 +12,85 @@ --- vim.print(list) --> "{ 1, 2, 3 }" --- ``` ----@addtogroup lua-vimscript ----@brief <pre>help ----vim.call({func}, {...}) *vim.call()* ---- Invokes |vim-function| or |user-function| {func} with arguments {...}. ---- See also |vim.fn|. ---- Equivalent to: >lua ---- vim.fn[func]({...}) ----< ----vim.cmd({command}) ---- See |vim.cmd()|. ---- ----vim.fn.{func}({...}) *vim.fn* ---- Invokes |vim-function| or |user-function| {func} with arguments {...}. ---- To call autoload functions, use the syntax: >lua ---- vim.fn['some\#function']({...}) ----< ---- Unlike vim.api.|nvim_call_function()| this converts directly between Vim ---- objects and Lua objects. If the Vim function returns a float, it will be ---- represented directly as a Lua number. Empty lists and dictionaries both ---- are represented by an empty table. ---- ---- Note: |v:null| values as part of the return value is represented as ---- |vim.NIL| special value ---- ---- Note: vim.fn keys are generated lazily, thus `pairs(vim.fn)` only ---- enumerates functions that were called at least once. ---- ---- Note: The majority of functions cannot run in |api-fast| callbacks with some ---- undocumented exceptions which are allowed. ---- ---- *lua-vim-variables* ----The Vim editor global dictionaries |g:| |w:| |b:| |t:| |v:| can be accessed ----from Lua conveniently and idiomatically by referencing the `vim.*` Lua tables ----described below. In this way you can easily read and modify global Vimscript ----variables from Lua. ---- ----Example: >lua ---- ---- vim.g.foo = 5 -- Set the g:foo Vimscript variable. ---- print(vim.g.foo) -- Get and print the g:foo Vimscript variable. ---- vim.g.foo = nil -- Delete (:unlet) the Vimscript variable. ---- vim.b[2].foo = 6 -- Set b:foo for buffer 2 ----< ---- ----Note that setting dictionary fields directly will not write them back into ----Nvim. This is because the index into the namespace simply returns a copy. ----Instead the whole dictionary must be written as one. This can be achieved by ----creating a short-lived temporary. ---- ----Example: >lua ---- ---- vim.g.my_dict.field1 = 'value' -- Does not work ---- ---- local my_dict = vim.g.my_dict -- ---- my_dict.field1 = 'value' -- Instead do ---- vim.g.my_dict = my_dict -- ---- ----vim.g *vim.g* ---- Global (|g:|) editor variables. ---- Key with no value returns `nil`. ---- ----vim.b *vim.b* ---- Buffer-scoped (|b:|) variables for the current buffer. ---- Invalid or unset key returns `nil`. Can be indexed with ---- an integer to access variables for a specific buffer. ---- ----vim.w *vim.w* ---- Window-scoped (|w:|) variables for the current window. ---- Invalid or unset key returns `nil`. Can be indexed with ---- an integer to access variables for a specific window. ---- ----vim.t *vim.t* ---- Tabpage-scoped (|t:|) variables for the current tabpage. ---- Invalid or unset key returns `nil`. Can be indexed with ---- an integer to access variables for a specific tabpage. ---- ----vim.v *vim.v* ---- |v:| variables. ---- Invalid or unset key returns `nil`. ----</pre> +--- @brief <pre>help +--- vim.call({func}, {...}) *vim.call()* +--- Invokes |vim-function| or |user-function| {func} with arguments {...}. +--- See also |vim.fn|. +--- Equivalent to: >lua +--- vim.fn[func]({...}) +--- < +--- vim.cmd({command}) +--- See |vim.cmd()|. +--- +--- vim.fn.{func}({...}) *vim.fn* +--- Invokes |vim-function| or |user-function| {func} with arguments {...}. +--- To call autoload functions, use the syntax: >lua +--- vim.fn['some#function']({...}) +--- < +--- Unlike vim.api.|nvim_call_function()| this converts directly between Vim +--- objects and Lua objects. If the Vim function returns a float, it will be +--- represented directly as a Lua number. Empty lists and dictionaries both +--- are represented by an empty table. +--- +--- Note: |v:null| values as part of the return value is represented as +--- |vim.NIL| special value +--- +--- Note: vim.fn keys are generated lazily, thus `pairs(vim.fn)` only +--- enumerates functions that were called at least once. +--- +--- Note: The majority of functions cannot run in |api-fast| callbacks with some +--- undocumented exceptions which are allowed. +--- +--- *lua-vim-variables* +--- The Vim editor global dictionaries |g:| |w:| |b:| |t:| |v:| can be accessed +--- from Lua conveniently and idiomatically by referencing the `vim.*` Lua tables +--- described below. In this way you can easily read and modify global Vimscript +--- variables from Lua. +--- +--- Example: >lua +--- +--- vim.g.foo = 5 -- Set the g:foo Vimscript variable. +--- print(vim.g.foo) -- Get and print the g:foo Vimscript variable. +--- vim.g.foo = nil -- Delete (:unlet) the Vimscript variable. +--- vim.b[2].foo = 6 -- Set b:foo for buffer 2 +--- < +--- +--- Note that setting dictionary fields directly will not write them back into +--- Nvim. This is because the index into the namespace simply returns a copy. +--- Instead the whole dictionary must be written as one. This can be achieved by +--- creating a short-lived temporary. +--- +--- Example: >lua +--- +--- vim.g.my_dict.field1 = 'value' -- Does not work +--- +--- local my_dict = vim.g.my_dict -- +--- my_dict.field1 = 'value' -- Instead do +--- vim.g.my_dict = my_dict -- +--- +--- vim.g *vim.g* +--- Global (|g:|) editor variables. +--- Key with no value returns `nil`. +--- +--- vim.b *vim.b* +--- Buffer-scoped (|b:|) variables for the current buffer. +--- Invalid or unset key returns `nil`. Can be indexed with +--- an integer to access variables for a specific buffer. +--- +--- vim.w *vim.w* +--- Window-scoped (|w:|) variables for the current window. +--- Invalid or unset key returns `nil`. Can be indexed with +--- an integer to access variables for a specific window. +--- +--- vim.t *vim.t* +--- Tabpage-scoped (|t:|) variables for the current tabpage. +--- Invalid or unset key returns `nil`. Can be indexed with +--- an integer to access variables for a specific tabpage. +--- +--- vim.v *vim.v* +--- |v:| variables. +--- Invalid or unset key returns `nil`. +--- </pre> local api = vim.api @@ -142,7 +139,6 @@ end --- vim.env.FOO = 'bar' --- print(vim.env.TERM) --- ``` ---- ---@param var string vim.env = setmetatable({}, { __index = function(_, k) @@ -205,31 +201,30 @@ local function new_win_opt_accessor(winid, bufnr) }) end ----@addtogroup lua-vimscript ----@brief <pre>help ----` ` *lua-options* ---- *lua-vim-options* ---- *lua-vim-set* ---- *lua-vim-setlocal* +--- @brief <pre>help +--- *lua-options* +--- *lua-vim-options* +--- *lua-vim-set* +--- *lua-vim-setlocal* --- ----Vim options can be accessed through |vim.o|, which behaves like Vimscript ----|:set|. +--- Vim options can be accessed through |vim.o|, which behaves like Vimscript +--- |:set|. --- ---- Examples: ~ +--- Examples: ~ --- ---- To set a boolean toggle: ---- Vimscript: `set number` ---- Lua: `vim.o.number = true` +--- To set a boolean toggle: +--- Vimscript: `set number` +--- Lua: `vim.o.number = true` --- ---- To set a string value: ---- Vimscript: `set wildignore=*.o,*.a,__pycache__` ---- Lua: `vim.o.wildignore = '*.o,*.a,__pycache__'` +--- To set a string value: +--- Vimscript: `set wildignore=*.o,*.a,__pycache__` +--- Lua: `vim.o.wildignore = '*.o,*.a,__pycache__'` --- ----Similarly, there is |vim.bo| and |vim.wo| for setting buffer-scoped and ----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|. ----</pre> +--- Similarly, there is |vim.bo| and |vim.wo| for setting buffer-scoped and +--- 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|. +--- </pre> --- Get or set |options|. Like `:set`. Invalid key is an error. --- @@ -310,13 +305,10 @@ vim.bo = new_buf_opt_accessor() --- ``` vim.wo = new_win_opt_accessor() ----@brief [[ --- vim.opt, vim.opt_local and vim.opt_global implementation --- --- To be used as helpers for working with options within neovim. --- For information on how to use, see :help vim.opt ---- ----@brief ]] --- Preserves the order and does not mutate the original list local function remove_duplicate_values(t) @@ -739,74 +731,73 @@ local function create_option_accessor(scope) }) end ----@addtogroup lua-vimscript ----@brief <pre>help ----` ` *vim.opt_local* ---- *vim.opt_global* ---- *vim.opt* ---- ---- ----A special interface |vim.opt| exists for conveniently interacting with list- ----and map-style option from Lua: It allows accessing them as Lua tables and ----offers object-oriented method for adding and removing entries. ---- ---- Examples: ~ ---- ---- The following methods of setting a list-style option are equivalent: ---- In Vimscript: >vim ---- set wildignore=*.o,*.a,__pycache__ ----< ---- In Lua using `vim.o`: >lua ---- vim.o.wildignore = '*.o,*.a,__pycache__' ----< ---- In Lua using `vim.opt`: >lua ---- vim.opt.wildignore = { '*.o', '*.a', '__pycache__' } ----< ---- To replicate the behavior of |:set+=|, use: >lua ---- ---- vim.opt.wildignore:append { "*.pyc", "node_modules" } ----< ---- To replicate the behavior of |:set^=|, use: >lua ---- ---- vim.opt.wildignore:prepend { "new_first_value" } ----< ---- To replicate the behavior of |:set-=|, use: >lua ---- ---- vim.opt.wildignore:remove { "node_modules" } ----< ---- The following methods of setting a map-style option are equivalent: ---- In Vimscript: >vim ---- set listchars=space:_,tab:>~ ----< ---- In Lua using `vim.o`: >lua ---- vim.o.listchars = 'space:_,tab:>~' ----< ---- In Lua using `vim.opt`: >lua ---- vim.opt.listchars = { space = '_', tab = '>~' } ----< ---- ----Note that |vim.opt| returns an `Option` object, not the value of the option, ----which is accessed through |vim.opt:get()|: ---- ---- Examples: ~ ---- ---- The following methods of getting a list-style option are equivalent: ---- In Vimscript: >vim ---- echo wildignore ----< ---- In Lua using `vim.o`: >lua ---- print(vim.o.wildignore) ----< ---- In Lua using `vim.opt`: >lua ---- vim.print(vim.opt.wildignore:get()) ----< ---- ----In any of the above examples, to replicate the behavior |:setlocal|, use ----`vim.opt_local`. Additionally, to replicate the behavior of |:setglobal|, use ----`vim.opt_global`. ----</pre> - ---- @diagnostic disable-next-line:unused-local used for gen_vimdoc +--- @brief <pre>help +--- *vim.opt_local* +--- *vim.opt_global* +--- *vim.opt* +--- +--- +--- A special interface |vim.opt| exists for conveniently interacting with list- +--- and map-style option from Lua: It allows accessing them as Lua tables and +--- offers object-oriented method for adding and removing entries. +--- +--- Examples: ~ +--- +--- The following methods of setting a list-style option are equivalent: +--- In Vimscript: >vim +--- set wildignore=*.o,*.a,__pycache__ +--- < +--- In Lua using `vim.o`: >lua +--- vim.o.wildignore = '*.o,*.a,__pycache__' +--- < +--- In Lua using `vim.opt`: >lua +--- vim.opt.wildignore = { '*.o', '*.a', '__pycache__' } +--- < +--- To replicate the behavior of |:set+=|, use: >lua +--- +--- vim.opt.wildignore:append { "*.pyc", "node_modules" } +--- < +--- To replicate the behavior of |:set^=|, use: >lua +--- +--- vim.opt.wildignore:prepend { "new_first_value" } +--- < +--- To replicate the behavior of |:set-=|, use: >lua +--- +--- vim.opt.wildignore:remove { "node_modules" } +--- < +--- The following methods of setting a map-style option are equivalent: +--- In Vimscript: >vim +--- set listchars=space:_,tab:>~ +--- < +--- In Lua using `vim.o`: >lua +--- vim.o.listchars = 'space:_,tab:>~' +--- < +--- In Lua using `vim.opt`: >lua +--- vim.opt.listchars = { space = '_', tab = '>~' } +--- < +--- +--- Note that |vim.opt| returns an `Option` object, not the value of the option, +--- which is accessed through |vim.opt:get()|: +--- +--- Examples: ~ +--- +--- The following methods of getting a list-style option are equivalent: +--- In Vimscript: >vim +--- echo wildignore +--- < +--- In Lua using `vim.o`: >lua +--- print(vim.o.wildignore) +--- < +--- In Lua using `vim.opt`: >lua +--- vim.print(vim.opt.wildignore:get()) +--- < +--- +--- In any of the above examples, to replicate the behavior |:setlocal|, use +--- `vim.opt_local`. Additionally, to replicate the behavior of |:setglobal|, use +--- `vim.opt_global`. +--- </pre> + +--- @class vim.Option local Option = {} -- luacheck: no unused --- Returns a Lua-representation of the option. Boolean, number and string @@ -856,9 +847,7 @@ local Option = {} -- luacheck: no unused --- print("J is enabled!") --- end --- ``` ---- ---@return string|integer|boolean|nil value of option ----@diagnostic disable-next-line:unused-local used for gen_vimdoc function Option:get() end --- Append a value to string-style options. See |:set+=| @@ -869,7 +858,6 @@ function Option:get() end --- vim.opt.formatoptions:append('j') --- vim.opt.formatoptions = vim.opt.formatoptions + 'j' --- ``` ---- ---@param value string Value to append ---@diagnostic disable-next-line:unused-local used for gen_vimdoc function Option:append(value) end -- luacheck: no unused @@ -882,7 +870,6 @@ function Option:append(value) end -- luacheck: no unused --- vim.opt.wildignore:prepend('*.o') --- vim.opt.wildignore = vim.opt.wildignore ^ '*.o' --- ``` ---- ---@param value string Value to prepend ---@diagnostic disable-next-line:unused-local used for gen_vimdoc function Option:prepend(value) end -- luacheck: no unused @@ -895,7 +882,6 @@ function Option:prepend(value) end -- luacheck: no unused --- vim.opt.wildignore:remove('*.pyc') --- vim.opt.wildignore = vim.opt.wildignore - '*.pyc' --- ``` ---- ---@param value string Value to remove ---@diagnostic disable-next-line:unused-local used for gen_vimdoc function Option:remove(value) end -- luacheck: no unused diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua index 91f91b5879..49165c4db9 100644 --- a/runtime/lua/vim/diagnostic.lua +++ b/runtime/lua/vim/diagnostic.lua @@ -70,6 +70,7 @@ local M = {} --- @field linehl? table<vim.diagnostic.Severity,string> --- @field texthl? table<vim.diagnostic.Severity,string> +--- @nodoc --- @enum vim.diagnostic.Severity M.severity = { ERROR = 1, @@ -107,6 +108,7 @@ local global_diagnostic_options = { --- @field show? fun(namespace: integer, bufnr: integer, diagnostics: vim.Diagnostic[], opts?: vim.diagnostic.OptsResolved) --- @field hide? fun(namespace:integer, bufnr:integer) +--- @nodoc --- @type table<string,vim.diagnostic.Handler> M.handlers = setmetatable({}, { __newindex = function(t, name, handler) @@ -731,71 +733,71 @@ end --- - `function`: Function with signature (namespace, bufnr) that returns any of the above. --- ---@param opts vim.diagnostic.Opts? (table?) When omitted or "nil", retrieve the current ---- configuration. Otherwise, a configuration table with the following keys: +--- configuration. Otherwise, a configuration table with the following keys: --- - underline: (default true) Use underline for diagnostics. Options: ---- * severity: Only underline diagnostics matching the given ---- severity |diagnostic-severity| +--- * severity: Only underline diagnostics matching the given +--- severity |diagnostic-severity| --- - virtual_text: (default true) Use virtual text for diagnostics. If multiple diagnostics ---- are set for a namespace, one prefix per diagnostic + the last diagnostic ---- message are shown. In addition to the options listed below, the ---- "virt_text" options of |nvim_buf_set_extmark()| may also be used here ---- (e.g. "virt_text_pos" and "hl_mode"). ---- Options: ---- * severity: Only show virtual text for diagnostics matching the given ---- severity |diagnostic-severity| ---- * source: (boolean or string) Include the diagnostic source in virtual ---- text. Use "if_many" to only show sources if there is more than ---- one diagnostic source in the buffer. Otherwise, any truthy value ---- means to always show the diagnostic source. ---- * spacing: (number) Amount of empty spaces inserted at the beginning ---- of the virtual text. ---- * prefix: (string or function) prepend diagnostic message with prefix. ---- If a function, it must have the signature (diagnostic, i, total) ---- -> string, where {diagnostic} is of type |diagnostic-structure|, ---- {i} is the index of the diagnostic being evaluated, and {total} ---- is the total number of diagnostics for the line. This can be ---- used to render diagnostic symbols or error codes. ---- * suffix: (string or function) Append diagnostic message with suffix. ---- If a function, it must have the signature (diagnostic) -> ---- string, where {diagnostic} is of type |diagnostic-structure|. ---- This can be used to render an LSP diagnostic error code. ---- * format: (function) A function that takes a diagnostic as input and ---- returns a string. The return value is the text used to display ---- the diagnostic. Example: ---- <pre>lua ---- function(diagnostic) ---- if diagnostic.severity == vim.diagnostic.severity.ERROR then ---- return string.format("E: %s", diagnostic.message) ---- end ---- return diagnostic.message ---- end ---- </pre> +--- are set for a namespace, one prefix per diagnostic + the last diagnostic +--- message are shown. In addition to the options listed below, the +--- "virt_text" options of |nvim_buf_set_extmark()| may also be used here +--- (e.g. "virt_text_pos" and "hl_mode"). +--- Options: +--- * severity: Only show virtual text for diagnostics matching the given +--- severity |diagnostic-severity| +--- * source: (boolean or string) Include the diagnostic source in virtual +--- text. Use "if_many" to only show sources if there is more than +--- one diagnostic source in the buffer. Otherwise, any truthy value +--- means to always show the diagnostic source. +--- * spacing: (number) Amount of empty spaces inserted at the beginning +--- of the virtual text. +--- * prefix: (string or function) prepend diagnostic message with prefix. +--- If a function, it must have the signature (diagnostic, i, total) +--- -> string, where {diagnostic} is of type |diagnostic-structure|, +--- {i} is the index of the diagnostic being evaluated, and {total} +--- is the total number of diagnostics for the line. This can be +--- used to render diagnostic symbols or error codes. +--- * suffix: (string or function) Append diagnostic message with suffix. +--- If a function, it must have the signature (diagnostic) -> +--- string, where {diagnostic} is of type |diagnostic-structure|. +--- This can be used to render an LSP diagnostic error code. +--- * format: (function) A function that takes a diagnostic as input and +--- returns a string. The return value is the text used to display +--- the diagnostic. Example: +--- ```lua +--- function(diagnostic) +--- if diagnostic.severity == vim.diagnostic.severity.ERROR then +--- return string.format("E: %s", diagnostic.message) +--- end +--- return diagnostic.message +--- end +--- ``` --- - signs: (default true) Use signs for diagnostics |diagnostic-signs|. Options: ---- * severity: Only show signs for diagnostics matching the given ---- severity |diagnostic-severity| ---- * priority: (number, default 10) Base priority to use for signs. When ---- {severity_sort} is used, the priority of a sign is adjusted based on ---- its severity. Otherwise, all signs use the same priority. ---- * text: (table) A table mapping |diagnostic-severity| to the sign text ---- to display in the sign column. The default is to use "E", "W", "I", and "H" ---- for errors, warnings, information, and hints, respectively. Example: ---- <pre>lua ---- vim.diagnostic.config({ ---- signs = { text = { [vim.diagnostic.severity.ERROR] = 'E', ... } } ---- }) ---- </pre> ---- * numhl: (table) A table mapping |diagnostic-severity| to the highlight ---- group used for the line number where the sign is placed. ---- * linehl: (table) A table mapping |diagnostic-severity| to the highlight group ---- used for the whole line the sign is placed in. +--- * severity: Only show signs for diagnostics matching the given +--- severity |diagnostic-severity| +--- * priority: (number, default 10) Base priority to use for signs. When +--- {severity_sort} is used, the priority of a sign is adjusted based on +--- its severity. Otherwise, all signs use the same priority. +--- * text: (table) A table mapping |diagnostic-severity| to the sign text +--- to display in the sign column. The default is to use "E", "W", "I", and "H" +--- for errors, warnings, information, and hints, respectively. Example: +--- ```lua +--- vim.diagnostic.config({ +--- signs = { text = { [vim.diagnostic.severity.ERROR] = 'E', ... } } +--- }) +--- ``` +--- * numhl: (table) A table mapping |diagnostic-severity| to the highlight +--- group used for the line number where the sign is placed. +--- * linehl: (table) A table mapping |diagnostic-severity| to the highlight group +--- used for the whole line the sign is placed in. --- - float: Options for floating windows. See |vim.diagnostic.open_float()|. --- - update_in_insert: (default false) Update diagnostics in Insert mode (if false, --- diagnostics are updated on InsertLeave) --- - severity_sort: (default false) Sort diagnostics by severity. This affects the order in ---- which signs and virtual text are displayed. When true, higher severities ---- are displayed before lower severities (e.g. ERROR is displayed before WARN). ---- Options: ---- * reverse: (boolean) Reverse sort order +--- which signs and virtual text are displayed. When true, higher severities +--- are displayed before lower severities (e.g. ERROR is displayed before WARN). +--- Options: +--- * reverse: (boolean) Reverse sort order --- ---@param namespace integer? Update the options for the given namespace. When omitted, update the --- global diagnostic options. @@ -1090,8 +1092,8 @@ M.handlers.signs = { api.nvim_create_namespace(string.format('%s/diagnostic/signs', ns.name)) end - --- Handle legacy diagnostic sign definitions - --- These were deprecated in 0.10 and will be removed in 0.12 + -- Handle legacy diagnostic sign definitions + -- These were deprecated in 0.10 and will be removed in 0.12 if opts.signs and not opts.signs.text and not opts.signs.numhl and not opts.signs.texthl then for _, v in ipairs({ 'Error', 'Warn', 'Info', 'Hint' }) do local name = string.format('DiagnosticSign%s', v) @@ -1543,7 +1545,8 @@ end --- Overrides the setting from |vim.diagnostic.config()|. --- - suffix: Same as {prefix}, but appends the text to the diagnostic instead of --- prepending it. Overrides the setting from |vim.diagnostic.config()|. ----@return integer?, integer?: ({float_bufnr}, {win_id}) +---@return integer? float_bufnr +---@return integer? win_id function M.open_float(opts, ...) -- Support old (bufnr, opts) signature local bufnr --- @type integer? diff --git a/runtime/lua/vim/filetype.lua b/runtime/lua/vim/filetype.lua index b43072a725..e7971d8916 100644 --- a/runtime/lua/vim/filetype.lua +++ b/runtime/lua/vim/filetype.lua @@ -2279,9 +2279,9 @@ end --- Perform filetype detection. --- --- The filetype can be detected using one of three methods: ---- 1. Using an existing buffer ---- 2. Using only a file name ---- 3. Using only file contents +--- 1. Using an existing buffer +--- 2. Using only a file name +--- 3. Using only file contents --- --- Of these, option 1 provides the most accurate result as it uses both the buffer's filename and --- (optionally) the buffer contents. Options 2 and 3 can be used without an existing buffer, but diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua index 22612a7255..0af5fc4f30 100644 --- a/runtime/lua/vim/fs.lua +++ b/runtime/lua/vim/fs.lua @@ -320,7 +320,7 @@ end --- Normalize a path to a standard format. A tilde (~) character at the --- beginning of the path is expanded to the user's home directory and any ---- backslash (\\) characters are converted to forward slashes (/). Environment +--- backslash (\) characters are converted to forward slashes (/). Environment --- variables are also expanded. --- --- Examples: diff --git a/runtime/lua/vim/highlight.lua b/runtime/lua/vim/highlight.lua index b055cce49d..effe280dee 100644 --- a/runtime/lua/vim/highlight.lua +++ b/runtime/lua/vim/highlight.lua @@ -1,4 +1,4 @@ ----@defgroup vim.highlight +---@brief --- --- Nvim includes a function for highlighting a selection on yank. --- @@ -19,18 +19,19 @@ --- ```vim --- au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false} --- ``` +--- local api = vim.api local M = {} --- Table with default priorities used for highlighting: ---- - `syntax`: `50`, used for standard syntax highlighting ---- - `treesitter`: `100`, used for treesitter-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 +--- - `syntax`: `50`, used for standard syntax highlighting +--- - `treesitter`: `100`, used for treesitter-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 d720745110..798428014d 100644 --- a/runtime/lua/vim/iter.lua +++ b/runtime/lua/vim/iter.lua @@ -1,4 +1,4 @@ ----@defgroup vim.iter +--- @brief --- --- \*vim.iter()\* is an interface for |iterable|s: it wraps a table or function argument into an --- \*Iter\* object with methods (such as |Iter:filter()| and |Iter:map()|) that transform the @@ -66,6 +66,7 @@ ---@class IterMod ---@operator call:Iter + local M = {} ---@class Iter @@ -599,7 +600,7 @@ end --- -- 12 --- --- ``` ---- +---@param f any ---@return any function Iter.find(self, f) if type(f) ~= 'function' then @@ -645,6 +646,7 @@ end --- ---@see Iter.find --- +---@param f any ---@return any ---@diagnostic disable-next-line: unused-local function Iter.rfind(self, f) -- luacheck: no unused args @@ -724,6 +726,7 @@ function Iter.nextback(self) -- luacheck: no unused args error('nextback() requires a list-like table') end +--- @nodoc function ListIter.nextback(self) if self._head ~= self._tail then local inc = self._head < self._tail and 1 or -1 @@ -754,6 +757,7 @@ function Iter.peekback(self) -- luacheck: no unused args error('peekback() requires a list-like table') end +---@nodoc function ListIter.peekback(self) if self._head ~= self._tail then local inc = self._head < self._tail and 1 or -1 diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua index 8e4e123fe0..84e9b4197d 100644 --- a/runtime/lua/vim/keymap.lua +++ b/runtime/lua/vim/keymap.lua @@ -90,6 +90,8 @@ end --- vim.keymap.del({'n', 'i', 'v'}, '<leader>w', { buffer = 5 }) --- ``` --- +---@param modes string|string[] +---@param lhs string ---@param opts table|nil A table of optional arguments: --- - "buffer": (integer|boolean) Remove a mapping from the given buffer. --- When `0` or `true`, use the current buffer. diff --git a/runtime/lua/vim/loader.lua b/runtime/lua/vim/loader.lua index ec99e417c2..5f3da55544 100644 --- a/runtime/lua/vim/loader.lua +++ b/runtime/lua/vim/loader.lua @@ -190,7 +190,6 @@ function Loader.loader_lib(modname) local sysname = uv.os_uname().sysname:lower() or '' local is_win = sysname:find('win', 1, true) and not sysname:find('darwin', 1, true) local ret = M.find(modname, { patterns = is_win and { '.dll' } or { '.so' } })[1] - ---@type function?, string? if ret then -- Making function name in Lua 5.1 (see src/loadlib.c:mkfuncname) is -- a) strip prefix up to and including the first dash, if any @@ -208,15 +207,13 @@ end --- `loadfile` using the cache --- Note this has the mode and env arguments which is supported by LuaJIT and is 5.1 compatible. ---@param filename? string ----@param mode? "b"|"t"|"bt" +---@param _mode? "b"|"t"|"bt" ---@param env? table ---@return function?, string? error_message ---@private --- luacheck: ignore 312 -function Loader.loadfile(filename, mode, env) +function Loader.loadfile(filename, _mode, env) -- ignore mode, since we byte-compile the Lua source files - mode = nil - return Loader.load(normalize(filename), { mode = mode, env = env }) + return Loader.load(normalize(filename), { env = env }) end --- Checks whether two cache hashes are the same based on: @@ -273,14 +270,14 @@ end --- Finds Lua modules for the given module name. ---@param modname string Module name, or `"*"` to find the top-level modules instead ----@param opts? ModuleFindOpts (table|nil) Options for finding a module: +---@param opts? ModuleFindOpts (table) Options for finding a module: --- - rtp: (boolean) Search for modname in the runtime path (defaults to `true`) --- - paths: (string[]) Extra paths to search for modname (defaults to `{}`) --- - patterns: (string[]) List of patterns to use when searching for modules. --- A pattern is a string added to the basename of the Lua module being searched. --- (defaults to `{"/init.lua", ".lua"}`) --- - all: (boolean) Return all matches instead of just the first one (defaults to `false`) ----@return ModuleInfo[] (list) A list of results with the following properties: +---@return ModuleInfo[] (table) A list of results with the following properties: --- - modpath: (string) the path to the module --- - modname: (string) the name of the module --- - stat: (table|nil) the fs_stat of the module path. Won't be returned for `modname="*"` diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua index 3a74c3ee90..19497e40dc 100644 --- a/runtime/lua/vim/lsp.lua +++ b/runtime/lua/vim/lsp.lua @@ -206,99 +206,96 @@ end --- |vim.lsp.get_client_by_id()| or |vim.lsp.get_clients()|. --- --- - Methods: ---- ---- - request(method, params, [handler], bufnr) ---- Sends a request to the server. ---- This is a thin wrapper around {client.rpc.request} with some additional ---- checking. ---- If {handler} is not specified, If one is not found there, then an error will occur. ---- Returns: {status}, {[client_id]}. {status} is a boolean indicating if ---- the notification was successful. If it is `false`, then it will always ---- be `false` (the client has shutdown). ---- If {status} is `true`, the function returns {request_id} as the second ---- result. You can use this with `client.cancel_request(request_id)` ---- to cancel the request. ---- ---- - request_sync(method, params, timeout_ms, bufnr) ---- Sends a request to the server and synchronously waits for the response. ---- This is a wrapper around {client.request} ---- Returns: { err=err, result=result }, a dictionary, where `err` and `result` come from ---- the |lsp-handler|. On timeout, cancel or error, returns `(nil, err)` where `err` is a ---- string describing the failure reason. If the request was unsuccessful returns `nil`. ---- ---- - notify(method, params) ---- Sends a notification to an LSP server. ---- Returns: a boolean to indicate if the notification was successful. If ---- it is false, then it will always be false (the client has shutdown). ---- ---- - cancel_request(id) ---- Cancels a request with a given request id. ---- Returns: same as `notify()`. ---- ---- - stop([force]) ---- Stops a client, optionally with force. ---- By default, it will just ask the server to shutdown without force. ---- If you request to stop a client which has previously been requested to ---- shutdown, it will automatically escalate and force shutdown. ---- ---- - is_stopped() ---- Checks whether a client is stopped. ---- Returns: true if the client is fully stopped. ---- ---- - on_attach(client, bufnr) ---- Runs the on_attach function from the client's config if it was defined. ---- Useful for buffer-local setup. ---- ---- - supports_method(method, [opts]): boolean ---- Checks if a client supports a given method. ---- Always returns true for unknown off-spec methods. ---- [opts] is a optional `{bufnr?: integer}` table. ---- Some language server capabilities can be file specific. +--- - request(method, params, [handler], bufnr) +--- Sends a request to the server. +--- This is a thin wrapper around {client.rpc.request} with some additional +--- checking. +--- If {handler} is not specified, If one is not found there, then an error will occur. +--- Returns: {status}, {[client_id]}. {status} is a boolean indicating if +--- the notification was successful. If it is `false`, then it will always +--- be `false` (the client has shutdown). +--- If {status} is `true`, the function returns {request_id} as the second +--- result. You can use this with `client.cancel_request(request_id)` +--- to cancel the request. +--- +--- - request_sync(method, params, timeout_ms, bufnr) +--- Sends a request to the server and synchronously waits for the response. +--- This is a wrapper around {client.request} +--- Returns: { err=err, result=result }, a dictionary, where `err` and `result` come from +--- the |lsp-handler|. On timeout, cancel or error, returns `(nil, err)` where `err` is a +--- string describing the failure reason. If the request was unsuccessful returns `nil`. +--- +--- - notify(method, params) +--- Sends a notification to an LSP server. +--- Returns: a boolean to indicate if the notification was successful. If +--- it is false, then it will always be false (the client has shutdown). +--- +--- - cancel_request(id) +--- Cancels a request with a given request id. +--- Returns: same as `notify()`. +--- +--- - stop([force]) +--- Stops a client, optionally with force. +--- By default, it will just ask the server to shutdown without force. +--- If you request to stop a client which has previously been requested to +--- shutdown, it will automatically escalate and force shutdown. +--- +--- - is_stopped() +--- Checks whether a client is stopped. +--- Returns: true if the client is fully stopped. +--- +--- - on_attach(client, bufnr) +--- Runs the on_attach function from the client's config if it was defined. +--- Useful for buffer-local setup. +--- +--- - supports_method(method, [opts]): boolean +--- Checks if a client supports a given method. +--- Always returns true for unknown off-spec methods. +--- [opts] is a optional `{bufnr?: integer}` table. +--- Some language server capabilities can be file specific. --- --- - Members ---- - {id} (number): The id allocated to the client. +--- - {id} (number): The id allocated to the client. --- ---- - {name} (string): If a name is specified on creation, that will be ---- used. Otherwise it is just the client id. This is used for ---- logs and messages. +--- - {name} (string): If a name is specified on creation, that will be +--- used. Otherwise it is just the client id. This is used for +--- logs and messages. --- ---- - {rpc} (table): RPC client object, for low level interaction with the ---- client. See |vim.lsp.rpc.start()|. +--- - {rpc} (table): RPC client object, for low level interaction with the +--- client. See |vim.lsp.rpc.start()|. --- ---- - {offset_encoding} (string): The encoding used for communicating ---- with the server. You can modify this in the `config`'s `on_init` method ---- before text is sent to the server. +--- - {offset_encoding} (string): The encoding used for communicating +--- with the server. You can modify this in the `config`'s `on_init` method +--- before text is sent to the server. --- ---- - {handlers} (table): The handlers used by the client as described in |lsp-handler|. +--- - {handlers} (table): The handlers used by the client as described in |lsp-handler|. --- ---- - {commands} (table): Table of command name to function which is called if ---- any LSP action (code action, code lenses, ...) triggers the command. ---- Client commands take precedence over the global command registry. +--- - {commands} (table): Table of command name to function which is called if +--- any LSP action (code action, code lenses, ...) triggers the command. +--- Client commands take precedence over the global command registry. --- ---- - {requests} (table): The current pending requests in flight ---- to the server. Entries are key-value pairs with the key ---- being the request ID while the value is a table with `type`, ---- `bufnr`, and `method` key-value pairs. `type` is either "pending" ---- for an active request, or "cancel" for a cancel request. It will ---- be "complete" ephemerally while executing |LspRequest| autocmds ---- when replies are received from the server. +--- - {requests} (table): The current pending requests in flight +--- to the server. Entries are key-value pairs with the key +--- being the request ID while the value is a table with `type`, +--- `bufnr`, and `method` key-value pairs. `type` is either "pending" +--- for an active request, or "cancel" for a cancel request. It will +--- be "complete" ephemerally while executing |LspRequest| autocmds +--- when replies are received from the server. --- ---- - {config} (table): Reference of the table that was passed by the user ---- to |vim.lsp.start_client()|. +--- - {config} (table): Reference of the table that was passed by the user +--- to |vim.lsp.start_client()|. --- ---- - {server_capabilities} (table): Response from the server sent on ---- `initialize` describing the server's capabilities. +--- - {server_capabilities} (table): Response from the server sent on +--- `initialize` describing the server's capabilities. --- ---- - {progress} A ring buffer (|vim.ringbuf()|) containing progress messages ---- sent by the server. +--- - {progress} A ring buffer (|vim.ringbuf()|) containing progress messages +--- sent by the server. --- ---- - {settings} Map with language server specific settings. ---- See {config} in |vim.lsp.start_client()| +--- - {settings} Map with language server specific settings. +--- See {config} in |vim.lsp.start_client()| --- ---- - {flags} A table with flags for the client. See {config} in |vim.lsp.start_client()| -function lsp.client() - error() -end +--- - {flags} A table with flags for the client. See {config} in |vim.lsp.start_client()| +lsp.client = nil --- @class lsp.StartOpts --- @field reuse_client fun(client: lsp.Client, config: table): boolean @@ -581,9 +578,9 @@ end --- spawn. Must be specified using a table. --- Non-string values are coerced to string. --- Example: ---- <pre> ---- { PORT = 8080; HOST = "0.0.0.0"; } ---- </pre> +--- ``` +--- { PORT = 8080; HOST = "0.0.0.0"; } +--- ``` --- --- - detached: (boolean, default true) Daemonize the server process so that it runs in a --- separate process group from Nvim. Nvim will shutdown the process on exit, but if Nvim fails to @@ -598,8 +595,9 @@ end --- \|vim.lsp.protocol.make_client_capabilities()|, passed to the language --- server on initialization. Hint: use make_client_capabilities() and modify --- its result. ---- - Note: To send an empty dictionary use |vim.empty_dict()|, else it will be encoded as an ---- array. +--- +--- - Note: To send an empty dictionary use |vim.empty_dict()|, else it will be encoded as an +--- array. --- --- - handlers: Map of language server method names to |lsp-handler| --- @@ -645,9 +643,9 @@ end --- --- - on_exit Callback (code, signal, client_id) invoked on client --- exit. ---- - code: exit code of the process ---- - signal: number describing the signal used to terminate (if any) ---- - client_id: client handle +--- - code: exit code of the process +--- - signal: number describing the signal used to terminate (if any) +--- - client_id: client handle --- --- - on_attach: Callback (client, bufnr) invoked when client --- attaches to a buffer. @@ -656,13 +654,13 @@ end --- server in the initialize request. Invalid/empty values will default to "off" --- --- - flags: A table with flags for the client. The current (experimental) flags are: ---- - allow_incremental_sync (bool, default true): Allow using incremental sync for buffer edits ---- - debounce_text_changes (number, default 150): Debounce didChange ---- notifications to the server by the given number in milliseconds. No debounce ---- occurs if nil ---- - exit_timeout (number|boolean, default false): Milliseconds to wait for server to ---- exit cleanly after sending the "shutdown" request before sending kill -15. ---- If set to false, nvim exits immediately after sending the "shutdown" request to the server. +--- - allow_incremental_sync (bool, default true): Allow using incremental sync for buffer edits +--- - debounce_text_changes (number, default 150): Debounce didChange +--- notifications to the server by the given number in milliseconds. No debounce +--- occurs if nil +--- - exit_timeout (number|boolean, default false): Milliseconds to wait for server to +--- exit cleanly after sending the "shutdown" request before sending kill -15. +--- If set to false, nvim exits immediately after sending the "shutdown" request to the server. --- --- - root_dir: (string) Directory where the LSP --- server will base its workspaceFolders, rootUri, and rootPath @@ -1239,7 +1237,7 @@ end --- --- Currently only supports a single client. This can be set via --- `setlocal formatexpr=v:lua.vim.lsp.formatexpr()` but will typically or in `on_attach` ---- via ``vim.bo[bufnr].formatexpr = 'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})'``. +--- via `vim.bo[bufnr].formatexpr = 'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})'`. --- ---@param opts table options for customizing the formatting expression which takes the --- following optional keys: diff --git a/runtime/lua/vim/lsp/buf.lua b/runtime/lua/vim/lsp/buf.lua index 7fc5286a78..d2e92de083 100644 --- a/runtime/lua/vim/lsp/buf.lua +++ b/runtime/lua/vim/lsp/buf.lua @@ -12,7 +12,7 @@ local M = {} ---@param method (string) LSP method name ---@param params (table|nil) Parameters to send to the server ---@param handler (function|nil) See |lsp-handler|. Follows |lsp-handler-resolution| --- +--- ---@return table<integer, integer> client_request_ids Map of client-id:request-id pairs ---for all successful requests. ---@return function _cancel_all_requests Function which can be used to @@ -172,12 +172,13 @@ end --- --- - filter (function|nil): --- Predicate used to filter clients. Receives a client as argument and must return a ---- boolean. Clients matching the predicate are included. Example: <pre>lua ---- -- Never request typescript-language-server for formatting ---- vim.lsp.buf.format { ---- filter = function(client) return client.name ~= "tsserver" end ---- } ---- </pre> +--- boolean. Clients matching the predicate are included. Example: +--- ```lua +--- -- Never request typescript-language-server for formatting +--- vim.lsp.buf.format { +--- filter = function(client) return client.name ~= "tsserver" end +--- } +--- ``` --- --- - async boolean|nil --- If true the method won't block. Defaults to false. @@ -472,6 +473,7 @@ end --- Add the folder at path to the workspace folders. If {path} is --- not provided, the user will be prompted for a path using |input()|. +--- @param workspace_folder? string function M.add_workspace_folder(workspace_folder) workspace_folder = workspace_folder or npcall(vim.fn.input, 'Workspace Folder: ', vim.fn.expand('%:p:h'), 'dir') @@ -511,6 +513,7 @@ end --- Remove the folder at path from the workspace folders. If --- {path} is not provided, the user will be prompted for --- a path using |input()|. +--- @param workspace_folder? string function M.remove_workspace_folder(workspace_folder) workspace_folder = workspace_folder or npcall(vim.fn.input, 'Workspace Folder: ', vim.fn.expand('%:p:h')) @@ -725,15 +728,15 @@ end --- ---@param options table|nil Optional table which holds the following optional fields: --- - context: (table|nil) ---- Corresponds to `CodeActionContext` of the LSP specification: ---- - diagnostics (table|nil): ---- LSP `Diagnostic[]`. Inferred from the current ---- position if not provided. ---- - only (table|nil): ---- List of LSP `CodeActionKind`s used to filter the code actions. ---- Most language servers support values like `refactor` ---- or `quickfix`. ---- - triggerKind (number|nil): The reason why code actions were requested. +--- Corresponds to `CodeActionContext` of the LSP specification: +--- - diagnostics (table|nil): +--- LSP `Diagnostic[]`. Inferred from the current +--- position if not provided. +--- - only (table|nil): +--- List of LSP `CodeActionKind`s used to filter the code actions. +--- Most language servers support values like `refactor` +--- or `quickfix`. +--- - triggerKind (number|nil): The reason why code actions were requested. --- - filter: (function|nil) --- Predicate taking an `CodeAction` and returning a boolean. --- - apply: (boolean|nil) diff --git a/runtime/lua/vim/lsp/codelens.lua b/runtime/lua/vim/lsp/codelens.lua index 966c7f4d03..7aed6f99e3 100644 --- a/runtime/lua/vim/lsp/codelens.lua +++ b/runtime/lua/vim/lsp/codelens.lua @@ -258,6 +258,8 @@ end --- |lsp-handler| for the method `textDocument/codeLens` --- +---@param err lsp.ResponseError? +---@param result lsp.CodeLens[] ---@param ctx lsp.HandlerContext function M.on_codelens(err, result, ctx, _) if err then diff --git a/runtime/lua/vim/lsp/diagnostic.lua b/runtime/lua/vim/lsp/diagnostic.lua index 33051ab61c..1fa67fc473 100644 --- a/runtime/lua/vim/lsp/diagnostic.lua +++ b/runtime/lua/vim/lsp/diagnostic.lua @@ -1,5 +1,3 @@ ----@brief lsp-diagnostic - local protocol = require('vim.lsp.protocol') local ms = protocol.Methods @@ -287,6 +285,7 @@ end --- ) --- ``` --- +---@param _ lsp.ResponseError? ---@param result lsp.PublishDiagnosticsParams ---@param ctx lsp.HandlerContext ---@param config? vim.diagnostic.Opts Configuration table (see |vim.diagnostic.config()|). @@ -319,6 +318,7 @@ end --- ) --- ``` --- +---@param _ lsp.ResponseError? ---@param result lsp.DocumentDiagnosticReport ---@param ctx lsp.HandlerContext ---@param config table Configuration table (see |vim.diagnostic.config()|). diff --git a/runtime/lua/vim/lsp/handlers.lua b/runtime/lua/vim/lsp/handlers.lua index a9da812231..781d720486 100644 --- a/runtime/lua/vim/lsp/handlers.lua +++ b/runtime/lua/vim/lsp/handlers.lua @@ -368,6 +368,8 @@ end --- ) --- ``` --- +---@param _ lsp.ResponseError? +---@param result lsp.Hover ---@param ctx lsp.HandlerContext ---@param config table Configuration table. --- - border: (default=nil) @@ -464,7 +466,8 @@ M[ms.textDocument_implementation] = location_handler --- ) --- ``` --- ----@param result table Response from the language server +---@param _ lsp.ResponseError? +---@param result lsp.SignatureHelp Response from the language server ---@param ctx lsp.HandlerContext Client context ---@param config table Configuration table. --- - border: (default=nil) diff --git a/runtime/lua/vim/lsp/log.lua b/runtime/lua/vim/lsp/log.lua index a9d49bc8f4..018003bb81 100644 --- a/runtime/lua/vim/lsp/log.lua +++ b/runtime/lua/vim/lsp/log.lua @@ -165,7 +165,7 @@ end --- Checks whether the level is sufficient for logging. ---@param level integer log level ----@returns (bool) true if would log, false if not +---@return bool : true if would log, false if not function log.should_log(level) return level >= current_log_level end diff --git a/runtime/lua/vim/lsp/rpc.lua b/runtime/lua/vim/lsp/rpc.lua index e849bb4f2a..1455ab51fa 100644 --- a/runtime/lua/vim/lsp/rpc.lua +++ b/runtime/lua/vim/lsp/rpc.lua @@ -273,8 +273,6 @@ end ---@field notify_reply_callbacks table<integer, function> dict of message_id to callback ---@field transport vim.lsp.rpc.Transport ---@field dispatchers vim.lsp.rpc.Dispatchers - ----@class vim.lsp.rpc.Client local Client = {} ---@private diff --git a/runtime/lua/vim/lsp/sync.lua b/runtime/lua/vim/lsp/sync.lua index 62fa0b33f4..936579e003 100644 --- a/runtime/lua/vim/lsp/sync.lua +++ b/runtime/lua/vim/lsp/sync.lua @@ -53,7 +53,7 @@ local str_utf_end = vim.str_utf_end ---@param line string the line to index into ---@param byte integer the byte idx ---@param offset_encoding string utf-8|utf-16|utf-32|nil (default: utf-8) ---@returns integer the utf idx for the given encoding +---@return integer utf_idx for the given encoding local function byte_to_utf(line, byte, offset_encoding) -- convert to 0 based indexing for str_utfindex byte = byte - 1 @@ -204,7 +204,7 @@ end --- Normalized to the next codepoint. --- prev_end_range is the text range sent to the server representing the changed region. --- curr_end_range is the text that should be collected and sent to the server. --- +--- ---@param prev_lines string[] list of lines ---@param curr_lines string[] list of lines ---@param start_range vim.lsp.sync.Range diff --git a/runtime/lua/vim/lsp/util.lua b/runtime/lua/vim/lsp/util.lua index b60135f851..e371cb0e15 100644 --- a/runtime/lua/vim/lsp/util.lua +++ b/runtime/lua/vim/lsp/util.lua @@ -574,6 +574,7 @@ end --- ---@param text_document_edit table: a `TextDocumentEdit` object ---@param index integer: Optional index of the edit, if from a list of edits (or nil, if not from a list) +---@param offset_encoding? string ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentEdit function M.apply_text_document_edit(text_document_edit, index, offset_encoding) local text_document = text_document_edit.textDocument @@ -770,7 +771,7 @@ end --- ---@param workspace_edit table `WorkspaceEdit` ---@param offset_encoding string utf-8|utf-16|utf-32 (required) ---see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_applyEdit +---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_applyEdit function M.apply_workspace_edit(workspace_edit, offset_encoding) if offset_encoding == nil then vim.notify_once( @@ -1130,6 +1131,7 @@ end --- - for LocationLink, targetRange is shown (e.g., body of function definition) --- ---@param location table a single `Location` or `LocationLink` +---@param opts table ---@return integer|nil buffer id of float window ---@return integer|nil window id of float window function M.preview_location(location, opts) @@ -1243,6 +1245,7 @@ end --- --- If you want to open a popup with fancy markdown, use `open_floating_preview` instead --- +---@param bufnr integer ---@param contents table of lines to show in window ---@param opts table with optional fields --- - height of floating window @@ -1603,7 +1606,7 @@ end ---@param contents table of lines to show in window ---@param syntax string of syntax to set for opened buffer ---@param opts table with optional fields (additional keys are filtered with |vim.lsp.util.make_floating_popup_options()| ---- before they are passed on to |nvim_open_win()|) +--- before they are passed on to |nvim_open_win()|) --- - height: (integer) height of floating window --- - width: (integer) width of floating window --- - wrap: (boolean, default true) wrap long lines @@ -1868,6 +1871,7 @@ end --- Converts symbols to quickfix list items. --- ---@param symbols table DocumentSymbol[] or SymbolInformation[] +---@param bufnr integer function M.symbols_to_items(symbols, bufnr) local function _symbols_to_items(_symbols, _items, _bufnr) for _, symbol in ipairs(_symbols) do diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua index 5cf8390843..83fdfede89 100644 --- a/runtime/lua/vim/shared.lua +++ b/runtime/lua/vim/shared.lua @@ -6,6 +6,7 @@ -- or the test suite. (Eventually the test suite will be run in a worker process, -- so this wouldn't be a separate case to consider) +---@nodoc ---@diagnostic disable-next-line: lowercase-global vim = vim or {} @@ -191,8 +192,8 @@ end --- ---@param s string String to split ---@param sep string Separator or pattern ----@param opts (table|nil) Keyword arguments |kwargs| accepted by |vim.gsplit()| ----@return string[] List of split components +---@param opts? table Keyword arguments |kwargs| accepted by |vim.gsplit()| +---@return string[] : List of split components function vim.split(s, sep, opts) local t = {} for c in vim.gsplit(s, sep, opts) do @@ -206,9 +207,9 @@ end --- ---@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua --- ----@generic T: table +---@generic T ---@param t table<T, any> (table) Table ----@return T[] (list) List of keys +---@return T[] : List of keys function vim.tbl_keys(t) vim.validate({ t = { t, 't' } }) --- @cast t table<any,any> @@ -225,7 +226,7 @@ end --- ---@generic T ---@param t table<any, T> (table) Table ----@return T[] (list) List of values +---@return T[] : List of values function vim.tbl_values(t) vim.validate({ t = { t, 't' } }) @@ -243,7 +244,7 @@ end ---@generic T ---@param func fun(value: T): any (function) Function ---@param t table<any, T> (table) Table ----@return table Table of transformed values +---@return table : Table of transformed values function vim.tbl_map(func, t) vim.validate({ func = { func, 'c' }, t = { t, 't' } }) --- @cast t table<any,any> @@ -260,7 +261,7 @@ end ---@generic T ---@param func fun(value: T): boolean (function) Function ---@param t table<any, T> (table) Table ----@return T[] (table) Table of filtered values +---@return T[] : Table of filtered values function vim.tbl_filter(func, t) vim.validate({ func = { func, 'c' }, t = { t, 't' } }) --- @cast t table<any,any> @@ -401,7 +402,7 @@ end --- - "keep": use value from the leftmost map --- - "force": use value from the rightmost map ---@param ... table Two or more tables ----@return table Merged table +---@return table : Merged table function vim.tbl_extend(behavior, ...) return tbl_extend(behavior, false, ...) end @@ -456,7 +457,7 @@ end --- Add the reverse lookup values to an existing table. --- For example: ---- ``tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = 1 }`` +--- `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = 1 }` --- --- Note that this *modifies* the input. ---@param o table Table to add the reverse to @@ -493,7 +494,7 @@ end --- ---@param o table Table to index ---@param ... any Optional keys (0 or more, variadic) via which to index the table ----@return any Nested value indexed by key (if it exists), else nil +---@return any : Nested value indexed by key (if it exists), else nil function vim.tbl_get(o, ...) local keys = { ... } if #keys == 0 then @@ -519,8 +520,8 @@ end ---@generic T: table ---@param dst T List which will be modified and appended to ---@param src table List from which values will be inserted ----@param start (integer|nil) Start index on src. Defaults to 1 ----@param finish (integer|nil) Final index on src. Defaults to `#src` +---@param start integer? Start index on src. Defaults to 1 +---@param finish integer? Final index on src. Defaults to `#src` ---@return T dst function vim.list_extend(dst, src, start, finish) vim.validate({ @@ -666,7 +667,7 @@ end --- ---@see https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua ---@param t table Table ----@return integer Number of non-nil values in table +---@return integer : Number of non-nil values in table function vim.tbl_count(t) vim.validate({ t = { t, 't' } }) --- @cast t table<any,any> @@ -681,10 +682,10 @@ end --- Creates a copy of a table containing only elements from start to end (inclusive) --- ---@generic T ----@param list T[] (list) Table +---@param list T[] Table ---@param start integer|nil Start range of slice ---@param finish integer|nil End range of slice ----@return T[] (list) Copy of table sliced from start to finish (inclusive) +---@return T[] Copy of table sliced from start to finish (inclusive) function vim.list_slice(list, start, finish) local new_list = {} --- @type `T`[] for i = start or 1, finish or #list do @@ -840,38 +841,37 @@ do --- Usage example: --- --- ```lua - --- function user.new(name, age, hobbies) - --- vim.validate{ - --- name={name, 'string'}, - --- age={age, 'number'}, - --- hobbies={hobbies, 'table'}, - --- } - --- ... - --- end + --- function user.new(name, age, hobbies) + --- vim.validate{ + --- name={name, 'string'}, + --- age={age, 'number'}, + --- hobbies={hobbies, 'table'}, + --- } + --- ... + --- end --- ``` --- --- Examples with explicit argument values (can be run directly): --- --- ```lua - --- vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}} - --- --> NOP (success) + --- vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}} + --- --> NOP (success) --- - --- vim.validate{arg1={1, 'table'}} - --- --> error('arg1: expected table, got number') + --- vim.validate{arg1={1, 'table'}} + --- --> error('arg1: expected table, got number') --- - --- vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}} - --- --> error('arg1: expected even number, got 3') + --- vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}} + --- --> error('arg1: expected even number, got 3') --- ``` --- --- If multiple types are valid they can be given as a list. --- --- ```lua - --- vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}} - --- -- NOP (success) - --- - --- vim.validate{arg1={1, {'string', 'table'}}} - --- -- error('arg1: expected string|table, got number') + --- vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}} + --- -- NOP (success) --- + --- vim.validate{arg1={1, {'string', 'table'}}} + --- -- error('arg1: expected string|table, got number') --- ``` --- ---@param opt table<vim.validate.Type,vim.validate.Spec> (table) Names of parameters to validate. Each key is a parameter @@ -989,19 +989,19 @@ do --- Once the buffer is full, adding a new entry overrides the oldest entry. --- --- ```lua - --- local ringbuf = vim.ringbuf(4) - --- ringbuf:push("a") - --- ringbuf:push("b") - --- ringbuf:push("c") - --- ringbuf:push("d") - --- ringbuf:push("e") -- overrides "a" - --- print(ringbuf:pop()) -- returns "b" - --- print(ringbuf:pop()) -- returns "c" + --- local ringbuf = vim.ringbuf(4) + --- ringbuf:push("a") + --- ringbuf:push("b") + --- ringbuf:push("c") + --- ringbuf:push("d") + --- ringbuf:push("e") -- overrides "a" + --- print(ringbuf:pop()) -- returns "b" + --- print(ringbuf:pop()) -- returns "c" --- - --- -- Can be used as iterator. Pops remaining items: - --- for val in ringbuf do - --- print(val) - --- end + --- -- Can be used as iterator. Pops remaining items: + --- for val in ringbuf do + --- print(val) + --- end --- ``` --- --- Returns a Ringbuf instance with the following methods: diff --git a/runtime/lua/vim/snippet.lua b/runtime/lua/vim/snippet.lua index 7e37d84393..09b7576d97 100644 --- a/runtime/lua/vim/snippet.lua +++ b/runtime/lua/vim/snippet.lua @@ -245,8 +245,6 @@ function Session:set_group_gravity(index, right_gravity) end end ---- @class vim.snippet.Snippet ---- @field private _session? vim.snippet.Session local M = { session = nil } --- Displays the choices for the given tabstop as completion items. diff --git a/runtime/lua/vim/treesitter.lua b/runtime/lua/vim/treesitter.lua index e2197168f0..9b69f95f54 100644 --- a/runtime/lua/vim/treesitter.lua +++ b/runtime/lua/vim/treesitter.lua @@ -432,7 +432,7 @@ end --- Can be used in an ftplugin or FileType autocommand. --- --- Note: By default, disables regex syntax highlighting, which may be required for some plugins. ---- In this case, add ``vim.bo.syntax = 'on'`` after the call to `start`. +--- In this case, add `vim.bo.syntax = 'on'` after the call to `start`. --- --- Example: --- diff --git a/runtime/lua/vim/treesitter/_query_linter.lua b/runtime/lua/vim/treesitter/_query_linter.lua index 556c910feb..6ec997eb4a 100644 --- a/runtime/lua/vim/treesitter/_query_linter.lua +++ b/runtime/lua/vim/treesitter/_query_linter.lua @@ -197,7 +197,7 @@ function M.clear(buf) end --- @private ---- @param findstart integer +--- @param findstart 0|1 --- @param base string function M.omnifunc(findstart, base) if findstart == 1 then diff --git a/runtime/lua/vim/treesitter/highlighter.lua b/runtime/lua/vim/treesitter/highlighter.lua index 99cc9bea09..8fb591bc46 100644 --- a/runtime/lua/vim/treesitter/highlighter.lua +++ b/runtime/lua/vim/treesitter/highlighter.lua @@ -231,7 +231,6 @@ function TSHighlighter:on_changedtree(changes) end --- Gets the query used for @param lang --- ---@package ---@param lang string Language used by the highlighter. ---@return vim.treesitter.highlighter.Query diff --git a/runtime/lua/vim/treesitter/languagetree.lua b/runtime/lua/vim/treesitter/languagetree.lua index 79566f5eeb..d01da8be71 100644 --- a/runtime/lua/vim/treesitter/languagetree.lua +++ b/runtime/lua/vim/treesitter/languagetree.lua @@ -1,5 +1,3 @@ ---- @defgroup lua-treesitter-languagetree ---- --- @brief A \*LanguageTree\* contains a tree of parsers: the root treesitter parser for {lang} and --- any "injected" language parsers, which themselves may inject other languages, recursively. --- For example a Lua buffer containing some Vimscript commands needs multiple parsers to fully @@ -433,7 +431,7 @@ function LanguageTree:parse(range) local query_time = 0 local total_parse_time = 0 - --- At least 1 region is invalid + -- At least 1 region is invalid if not self:is_valid(true) then changes, no_regions_parsed, total_parse_time = self:_parse_regions(range) -- Need to run injections when we parsed something diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua index 5bb9e07a82..57272dbd60 100644 --- a/runtime/lua/vim/treesitter/query.lua +++ b/runtime/lua/vim/treesitter/query.lua @@ -231,7 +231,7 @@ end ---@param lang string Language to use for the query ---@param query_name string Name of the query (e.g. "highlights") --- ----@return vim.treesitter.Query|nil -- Parsed query. `nil` if no query files are found. +---@return vim.treesitter.Query|nil : Parsed query. `nil` if no query files are found. M.get = vim.func._memoize('concat-2', function(lang, query_name) if explicit_queries[lang][query_name] then return explicit_queries[lang][query_name] @@ -1019,6 +1019,8 @@ end --- vim.bo.omnifunc = 'v:lua.vim.treesitter.query.omnifunc' --- ``` --- +--- @param findstart 0|1 +--- @param base string function M.omnifunc(findstart, base) return vim.treesitter._query_linter.omnifunc(findstart, base) end diff --git a/runtime/lua/vim/uri.lua b/runtime/lua/vim/uri.lua index 038aa8acfb..7660dc42e7 100644 --- a/runtime/lua/vim/uri.lua +++ b/runtime/lua/vim/uri.lua @@ -1,4 +1,4 @@ ----TODO: This is implemented only for files currently. +-- TODO: This is implemented only for files currently. -- https://tools.ietf.org/html/rfc3986 -- https://tools.ietf.org/html/rfc2732 -- https://tools.ietf.org/html/rfc2396 @@ -116,7 +116,6 @@ end ---Gets the buffer for a uri. ---Creates a new unloaded buffer if no buffer for the uri already exists. --- ---@param uri string ---@return integer bufnr function M.uri_to_bufnr(uri) diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua index 58c2a2386d..09a6fa825b 100644 --- a/runtime/lua/vim/version.lua +++ b/runtime/lua/vim/version.lua @@ -1,6 +1,5 @@ ---- @defgroup vim.version ---- ---- @brief The \`vim.version\` module provides functions for comparing versions and ranges +--- @brief +--- The `vim.version` module provides functions for comparing versions and ranges --- conforming to the https://semver.org spec. Plugins, and plugin managers, can use this to check --- available tools and dependencies on the current system. --- @@ -13,9 +12,9 @@ --- end --- ``` --- ---- \*vim.version()\* returns the version of the current Nvim process. +--- *vim.version()* returns the version of the current Nvim process. --- ---- VERSION RANGE SPEC \*version-range\* +--- VERSION RANGE SPEC *version-range* --- --- A version "range spec" defines a semantic version range which can be tested against a version, --- using |vim.version.range()|. |