mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-09-06 19:38:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(gen): support language annotation in docstrings

Browse Source
This commit is contained in:
Christian Clason
2022-11-23 12:31:49 +01:00
parent 9e1187e489
commit 0b05bd87c0
27 changed files with 259 additions and 261 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
runtime/doc/api.txt
View File

@@ -803,7 +803,7 @@ nvim_feedkeys({keys}, {mode}, {escape_ks}) *nvim_feedkeys()*
with escape_ks=false) to replace |keycodes|, then pass the result to with escape_ks=false) to replace |keycodes|, then pass the result to
nvim_feedkeys(). nvim_feedkeys().
Example: > Example: >vim
:let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true) :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true)
:call nvim_feedkeys(key, 'n', v:false) :call nvim_feedkeys(key, 'n', v:false)
< <
@@ -859,7 +859,7 @@ nvim_get_color_by_name({name}) *nvim_get_color_by_name()*
Returns the 24-bit RGB value of a |nvim_get_color_map()| color name or Returns the 24-bit RGB value of a |nvim_get_color_map()| color name or
"#rrggbb" hexadecimal string. "#rrggbb" hexadecimal string.
Example: > Example: >vim
:echo nvim_get_color_by_name("Pink") :echo nvim_get_color_by_name("Pink")
:echo nvim_get_color_by_name("#cbcbcb") :echo nvim_get_color_by_name("#cbcbcb")
< <
@@ -1444,11 +1444,11 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts}) *nvim_set_keymap()*
Unlike |:map|, leading/trailing whitespace is accepted as part of the Unlike |:map|, leading/trailing whitespace is accepted as part of the
{lhs} or {rhs}. Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual. {lhs} or {rhs}. Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual.
Example: > Example: >vim
call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true}) call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})
< <
is equivalent to: > is equivalent to: >vim
nmap <nowait> <Space><NL> <Nop> nmap <nowait> <Space><NL> <Nop>
< <
@@ -1746,7 +1746,7 @@ nvim_create_user_command({name}, {command}, {*opts})
{command} is the replacement text or Lua function to execute. {command} is the replacement text or Lua function to execute.
Example: > Example: >vim
:call nvim_create_user_command('SayHello', 'echo "Hello world!"', {}) :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {})
:SayHello :SayHello
Hello world! Hello world!
@@ -2027,7 +2027,7 @@ whether a buffer is loaded.
nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
Activates buffer-update events on a channel, or as Lua callbacks. Activates buffer-update events on a channel, or as Lua callbacks.
Example (Lua): capture buffer updates in a global `events` variable (use "print(vim.inspect(events))" to see its contents): > Example (Lua): capture buffer updates in a global `events` variable (use "print(vim.inspect(events))" to see its contents): >lua
events = {} events = {}
vim.api.nvim_buf_attach(0, false, { vim.api.nvim_buf_attach(0, false, {
on_lines=function(...) table.insert(events, {...}) end}) on_lines=function(...) table.insert(events, {...}) end})
@@ -2529,29 +2529,27 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
Region can be given as (row,col) tuples, or valid extmark ids (whose 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) positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1)
respectively, thus the following are equivalent: respectively, thus the following are equivalent: >lua
> nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
nvim_buf_get_extmarks(0, my_ns, 0, -1, {}) nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {})
nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {})
< <
If `end` is less than `start`, traversal works backwards. (Useful with If `end` is less than `start`, traversal works backwards. (Useful with
`limit`, to get the first marks prior to a given position.) `limit`, to get the first marks prior to a given position.)
Example: Example: >lua
> local a = vim.api
local a = vim.api local pos = a.nvim_win_get_cursor(0)
local pos = a.nvim_win_get_cursor(0) local ns = a.nvim_create_namespace('my-plugin')
local ns = a.nvim_create_namespace('my-plugin') -- Create new extmark at line 1, column 1.
-- Create new extmark at line 1, column 1. local m1 = a.nvim_buf_set_extmark(0, ns, 0, 0, {})
local m1 = a.nvim_buf_set_extmark(0, ns, 0, 0, {}) -- Create new extmark at line 3, column 1.
-- Create new extmark at line 3, column 1. local m2 = a.nvim_buf_set_extmark(0, ns, 0, 2, {})
local m2 = a.nvim_buf_set_extmark(0, ns, 0, 2, {}) -- Get extmarks only from line 3.
-- Get extmarks only from line 3. local ms = a.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {})
local ms = a.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {}) -- Get all marks in this buffer + namespace.
-- Get all marks in this buffer + namespace. local all = a.nvim_buf_get_extmarks(0, ns, 0, -1, {})
local all = a.nvim_buf_get_extmarks(0, ns, 0, -1, {}) print(vim.inspect(ms))
print(vim.inspect(ms))
< <
Parameters: ~ Parameters: ~
@@ -2969,12 +2967,12 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()*
could let floats hover outside of the main window like a tooltip, but this could let floats hover outside of the main window like a tooltip, but this
should not be used to specify arbitrary WM screen positions. should not be used to specify arbitrary WM screen positions.
Example (Lua): window-relative float > Example (Lua): window-relative float >lua
vim.api.nvim_open_win(0, false, vim.api.nvim_open_win(0, false,
{relative='win', row=3, col=3, width=12, height=3}) {relative='win', row=3, col=3, width=12, height=3})
< <
Example (Lua): buffer-relative float (travels as buffer is scrolled) > Example (Lua): buffer-relative float (travels as buffer is scrolled) >lua
vim.api.nvim_open_win(0, false, vim.api.nvim_open_win(0, false,
{relative='win', width=12, height=3, bufpos={100,10}}) {relative='win', width=12, height=3, bufpos={100,10}})
< <
@@ -3210,7 +3208,7 @@ nvim_clear_autocmds({*opts}) *nvim_clear_autocmds()*
nvim_create_augroup({name}, {*opts}) *nvim_create_augroup()* nvim_create_augroup({name}, {*opts}) *nvim_create_augroup()*
Create or get an autocommand group |autocmd-groups|. Create or get an autocommand group |autocmd-groups|.
To get an existing group id, do: > To get an existing group id, do: >lua
local id = vim.api.nvim_create_augroup("MyGroup", { local id = vim.api.nvim_create_augroup("MyGroup", {
clear = false clear = false
}) })
@@ -3235,7 +3233,7 @@ nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()*
executed when the autocommand triggers: a callback function (Lua or executed when the autocommand triggers: a callback function (Lua or
Vimscript), or a command (like regular autocommands). Vimscript), or a command (like regular autocommands).
Example using callback: > Example using callback: >lua
-- Lua function -- Lua function
local myluafun = function() print("This buffer enters") end local myluafun = function() print("This buffer enters") end
@@ -3250,40 +3248,39 @@ nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()*
Lua functions receive a table with information about the autocmd event as Lua functions receive a table with information about the autocmd event as
an argument. To use a function which itself accepts another (optional) an argument. To use a function which itself accepts another (optional)
parameter, wrap the function in a lambda: parameter, wrap the function in a lambda: >lua
> -- Lua function with an optional parameter.
-- Lua function with an optional parameter. -- The autocmd callback would pass a table as argument but this
-- The autocmd callback would pass a table as argument but this -- function expects number|nil
-- function expects number|nil local myluafun = function(bufnr) bufnr = bufnr or vim.api.nvim_get_current_buf() end
local myluafun = function(bufnr) bufnr = bufnr or vim.api.nvim_get_current_buf() end
vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
pattern = {"*.c", "*.h"}, pattern = {"*.c", "*.h"},
callback = function() myluafun() end, callback = function() myluafun() end,
}) })
< <
Example using command: > Example using command: >lua
vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
pattern = {"*.c", "*.h"}, pattern = {"*.c", "*.h"},
command = "echo 'Entering a C or C++ file'", command = "echo 'Entering a C or C++ file'",
}) })
< <
Example values for pattern: > Example values for pattern: >lua
pattern = "*.py" pattern = "*.py"
pattern = { "*.py", "*.pyi" } pattern = { "*.py", "*.pyi" }
< <
Note: The `pattern` is passed to callbacks and commands as a literal string; environment Note: The `pattern` is passed to callbacks and commands as a literal string; environment
variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|. Instead, variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|. Instead,
|expand()| such variables explicitly: > |expand()| such variables explicitly: >lua
pattern = vim.fn.expand("~") .. "/some/path/*.py" pattern = vim.fn.expand("~") .. "/some/path/*.py"
< <
Example values for event: > Example values for event: >lua
"BufWritePre" event = "BufWritePre"
{"CursorHold", "BufWritePre", "BufWritePost"} event = {"CursorHold", "BufWritePre", "BufWritePost"}
< <
Parameters: ~ Parameters: ~
@@ -3394,7 +3391,7 @@ nvim_exec_autocmds({event}, {*opts}) *nvim_exec_autocmds()*
nvim_get_autocmds({*opts}) *nvim_get_autocmds()* nvim_get_autocmds({*opts}) *nvim_get_autocmds()*
Get all autocommands that match the corresponding {opts}. Get all autocommands that match the corresponding {opts}.
These examples will get autocommands matching ALL the given criteria: > These examples will get autocommands matching ALL the given criteria: >lua
-- Matches all criteria -- Matches all criteria
autocommands = vim.api.nvim_get_autocmds({ autocommands = vim.api.nvim_get_autocmds({
group = "MyGroup", group = "MyGroup",

6
runtime/doc/develop.txt
View File

@@ -185,6 +185,7 @@ Docstring format:
- Limited markdown is supported. - Limited markdown is supported.
- List-items start with `-` (useful to nest or "indent") - List-items start with `-` (useful to nest or "indent")
- Use `<pre>` for code samples. - Use `<pre>` for code samples.
Code samples can be annotated as `vim` or `lua`
Example: the help for |nvim_open_win()| is generated from a docstring defined Example: the help for |nvim_open_win()| is generated from a docstring defined
in src/nvim/api/win_config.c like this: > in src/nvim/api/win_config.c like this: >
@@ -193,7 +194,7 @@ in src/nvim/api/win_config.c like this: >
/// ... /// ...
/// ///
/// Example (Lua): window-relative float /// Example (Lua): window-relative float
/// <pre> /// <pre>lua
/// vim.api.nvim_open_win(0, false, /// vim.api.nvim_open_win(0, false,
/// {relative='win', row=3, col=3, width=12, height=3}) /// {relative='win', row=3, col=3, width=12, height=3})
/// </pre> /// </pre>
@@ -223,6 +224,7 @@ Docstring format:
- Limited markdown is supported. - Limited markdown is supported.
- List-items start with `-` (useful to nest or "indent") - List-items start with `-` (useful to nest or "indent")
- Use `<pre>` for code samples. - Use `<pre>` for code samples.
Code samples can be annotated as `vim` or `lua`
Example: the help for |vim.paste()| is generated from a docstring decorating Example: the help for |vim.paste()| is generated from a docstring decorating
vim.paste in runtime/lua/vim/_editor.lua like this: > vim.paste in runtime/lua/vim/_editor.lua like this: >
@@ -231,7 +233,7 @@ vim.paste in runtime/lua/vim/_editor.lua like this: >
--- (such as the |TUI|) pastes text into the editor. --- (such as the |TUI|) pastes text into the editor.
--- ---
--- Example: To remove ANSI color codes when pasting: --- Example: To remove ANSI color codes when pasting:
--- <pre> --- <pre>lua
--- vim.paste = (function() --- vim.paste = (function()
--- local overridden = vim.paste --- local overridden = vim.paste
--- ... --- ...

26
runtime/doc/diagnostic.txt
View File

@@ -320,12 +320,12 @@ config({opts}, {namespace}) *vim.diagnostic.config()*
|vim.diagnostic.show()|). Ephemeral configuration has highest priority, |vim.diagnostic.show()|). Ephemeral configuration has highest priority,
followed by namespace configuration, and finally global configuration. followed by namespace configuration, and finally global configuration.
For example, if a user enables virtual text globally with > For example, if a user enables virtual text globally with >lua
vim.diagnostic.config({ virtual_text = true }) vim.diagnostic.config({ virtual_text = true })
< <
and a diagnostic producer sets diagnostics with > and a diagnostic producer sets diagnostics with >lua
vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false }) vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false })
< <
@@ -372,14 +372,14 @@ config({opts}, {namespace}) *vim.diagnostic.config()*
to render an LSP diagnostic error code. to render an LSP diagnostic error code.
• format: (function) A function that takes a diagnostic • format: (function) A function that takes a diagnostic
as input and returns a string. The return value is as input and returns a string. The return value is
the text used to display the diagnostic. Example: > the text used to display the diagnostic. Example: >lua
function(diagnostic) function(diagnostic)
if diagnostic.severity == vim.diagnostic.severity.ERROR then if diagnostic.severity == vim.diagnostic.severity.ERROR then
return string.format("E: %s", diagnostic.message) return string.format("E: %s", diagnostic.message)
end
return diagnostic.message
end end
return diagnostic.message
end
< <
• signs: (default true) Use signs for diagnostics. • signs: (default true) Use signs for diagnostics.
@@ -553,12 +553,12 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults})
WARNING filename:27:3: Variable 'foo' does not exist WARNING filename:27:3: Variable 'foo' does not exist
< <
This can be parsed into a diagnostic |diagnostic-structure| with: > This can be parsed into a diagnostic |diagnostic-structure| with: >lua
local s = "WARNING filename:27:3: Variable 'foo' does not exist" local s = "WARNING filename:27:3: Variable 'foo' does not exist"
local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$" local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
local groups = { "severity", "lnum", "col", "message" } local groups = { "severity", "lnum", "col", "message" }
vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN }) vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN })
< <
Parameters: ~ Parameters: ~

79
runtime/doc/lsp.txt
View File

@@ -681,7 +681,7 @@ for_each_buffer_client({bufnr}, {fn})
• {bufnr} (number) Buffer number • {bufnr} (number) Buffer number
• {fn} (function) Function to run on each client attached to buffer • {fn} (function) Function to run on each client attached to buffer
{bufnr}. The function takes the client, client ID, and buffer {bufnr}. The function takes the client, client ID, and buffer
number as arguments. Example: > number as arguments. Example: >lua
vim.lsp.for_each_buffer_client(0, function(client, client_id, bufnr) vim.lsp.for_each_buffer_client(0, function(client, client_id, bufnr)
print(vim.inspect(client)) print(vim.inspect(client))
@@ -780,14 +780,13 @@ start({config}, {opts}) *vim.lsp.start()*
running client if one is found matching `name` and `root_dir`. Attaches running client if one is found matching `name` and `root_dir`. Attaches
the current buffer to the client. the current buffer to the client.
Example: Example: >lua
>
vim.lsp.start({ vim.lsp.start({
name = 'my-server-name', name = 'my-server-name',
cmd = {'name-of-language-server-executable'}, cmd = {'name-of-language-server-executable'},
root_dir = vim.fs.dirname(vim.fs.find({'pyproject.toml', 'setup.py'}, { upward = true })[1]), root_dir = vim.fs.dirname(vim.fs.find({'pyproject.toml', 'setup.py'}, { upward = true })[1]),
}) })
< <
See |vim.lsp.start_client()| for all available options. The most important See |vim.lsp.start_client()| for all available options. The most important
@@ -964,11 +963,9 @@ start_client({config}) *vim.lsp.start_client()*
stop_client({client_id}, {force}) *vim.lsp.stop_client()* stop_client({client_id}, {force}) *vim.lsp.stop_client()*
Stops a client(s). Stops a client(s).
You can also use the `stop()` function on a |vim.lsp.client| object. To You can also use the `stop()` function on a |vim.lsp.client| object. To stop all clients: >lua
stop all clients:
>
vim.lsp.stop_client(vim.lsp.get_active_clients()) vim.lsp.stop_client(vim.lsp.get_active_clients())
< <
By default asks the server to shutdown, unless stop was requested already By default asks the server to shutdown, unless stop was requested already
@@ -1078,11 +1075,10 @@ definition({options}) *vim.lsp.buf.definition()*
document_highlight() *vim.lsp.buf.document_highlight()* document_highlight() *vim.lsp.buf.document_highlight()*
Send request to the server to resolve document highlights for the current Send request to the server to resolve document highlights for the current
text document position. This request can be triggered by a key mapping or text document position. This request can be triggered by a key mapping or
by events such as `CursorHold`, e.g.: by events such as `CursorHold` , e.g.: >vim
> autocmd CursorHold <buffer> lua vim.lsp.buf.document_highlight()
autocmd CursorHold <buffer> lua vim.lsp.buf.document_highlight() autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight()
autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight() autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references()
autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references()
< <
Note: Usage of |vim.lsp.buf.document_highlight()| requires the following Note: Usage of |vim.lsp.buf.document_highlight()| requires the following
@@ -1126,12 +1122,12 @@ format({options}) *vim.lsp.buf.format()*
buffer (0). buffer (0).
• filter (function|nil): Predicate used to filter clients. • filter (function|nil): Predicate used to filter clients.
Receives a client as argument and must return a boolean. Receives a client as argument and must return a boolean.
Clients matching the predicate are included. Example: • > Clients matching the predicate are included. Example: • >lua
-- Never request typescript-language-server for formatting -- Never request typescript-language-server for formatting
vim.lsp.buf.format { vim.lsp.buf.format {
filter = function(client) return client.name ~= "tsserver" end filter = function(client) return client.name ~= "tsserver" end
} }
< <
• async boolean|nil If true the method won't block. • async boolean|nil If true the method won't block.
Defaults to false. Editing the buffer while formatting Defaults to false. Editing the buffer while formatting
@@ -1253,7 +1249,7 @@ on_publish_diagnostics({_}, {result}, {ctx}, {config})
|lsp-handler| for the method "textDocument/publishDiagnostics" |lsp-handler| for the method "textDocument/publishDiagnostics"
See |vim.diagnostic.config()| for configuration options. Handler-specific See |vim.diagnostic.config()| for configuration options. Handler-specific
configuration can be set using |vim.lsp.with()|: > configuration can be set using |vim.lsp.with()|: >lua
vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with( vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
vim.lsp.diagnostic.on_publish_diagnostics, { vim.lsp.diagnostic.on_publish_diagnostics, {
@@ -1306,8 +1302,9 @@ refresh() *vim.lsp.codelens.refresh()*
Refresh the codelens for the current buffer Refresh the codelens for the current buffer
It is recommended to trigger this using an autocmd or via keymap. It is recommended to trigger this using an autocmd or via keymap.
>
autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh() Example: >vim
autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh()
< <
run() *vim.lsp.codelens.run()* run() *vim.lsp.codelens.run()*
@@ -1326,16 +1323,16 @@ save({lenses}, {bufnr}, {client_id}) *vim.lsp.codelens.save()*
Lua module: vim.lsp.handlers *lsp-handlers* Lua module: vim.lsp.handlers *lsp-handlers*
hover({_}, {result}, {ctx}, {config}) *vim.lsp.handlers.hover()* hover({_}, {result}, {ctx}, {config}) *vim.lsp.handlers.hover()*
|lsp-handler| for the method "textDocument/hover" > |lsp-handler| for the method "textDocument/hover" >lua
vim.lsp.handlers["textDocument/hover"] = vim.lsp.with( vim.lsp.handlers["textDocument/hover"] = vim.lsp.with(
vim.lsp.handlers.hover, { vim.lsp.handlers.hover, {
-- Use a sharp border with `FloatBorder` highlights -- Use a sharp border with `FloatBorder` highlights
border = "single", border = "single",
-- add the title in hover float window -- add the title in hover float window
title = "hover" title = "hover"
} }
) )
< <
Parameters: ~ Parameters: ~
@@ -1347,14 +1344,14 @@ hover({_}, {result}, {ctx}, {config}) *vim.lsp.handlers.hover()*
*vim.lsp.handlers.signature_help()* *vim.lsp.handlers.signature_help()*
signature_help({_}, {result}, {ctx}, {config}) signature_help({_}, {result}, {ctx}, {config})
|lsp-handler| for the method "textDocument/signatureHelp". The active |lsp-handler| for the method "textDocument/signatureHelp". The active
parameter is highlighted with |hl-LspSignatureActiveParameter|. > parameter is highlighted with |hl-LspSignatureActiveParameter|. >lua
vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with( vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with(
vim.lsp.handlers.signature_help, { vim.lsp.handlers.signature_help, {
-- Use a sharp border with `FloatBorder` highlights -- Use a sharp border with `FloatBorder` highlights
border = "single" border = "single"
} }
) )
< <
Parameters: ~ Parameters: ~

97
runtime/doc/lua.txt
View File

@@ -1302,7 +1302,7 @@ cmd({command}) *vim.cmd()*
Note that `vim.cmd` can be indexed with a command name to return a Note that `vim.cmd` can be indexed with a command name to return a
callable function to the command. callable function to the command.
Example: > Example: >lua
vim.cmd('echo 42') vim.cmd('echo 42')
vim.cmd([[ vim.cmd([[
@@ -1436,7 +1436,7 @@ paste({lines}, {phase}) *vim.paste()*
Paste handler, invoked by |nvim_paste()| when a conforming UI (such as the Paste handler, invoked by |nvim_paste()| when a conforming UI (such as the
|TUI|) pastes text into the editor. |TUI|) pastes text into the editor.
Example: To remove ANSI color codes when pasting: > Example: To remove ANSI color codes when pasting: >lua
vim.paste = (function(overridden) vim.paste = (function(overridden)
return function(lines, phase) return function(lines, phase)
@@ -1465,7 +1465,7 @@ paste({lines}, {phase}) *vim.paste()*
|paste| @alias paste_phase -1 | 1 | 2 | 3 |paste| @alias paste_phase -1 | 1 | 2 | 3
pretty_print({...}) *vim.pretty_print()* pretty_print({...}) *vim.pretty_print()*
Prints given arguments in human-readable format. Example: > Prints given arguments in human-readable format. Example: >lua
-- Print highlight group Normal and store it's contents in a variable. -- Print highlight group Normal and store it's contents in a variable.
local hl_normal = vim.pretty_print(vim.api.nvim_get_hl_by_name("Normal", true)) local hl_normal = vim.pretty_print(vim.api.nvim_get_hl_by_name("Normal", true))
< <
@@ -1544,10 +1544,11 @@ defaulttable({create}) *vim.defaulttable()*
If {create} is `nil`, this will create a defaulttable whose constructor If {create} is `nil`, this will create a defaulttable whose constructor
function is this function, effectively allowing to create nested tables on function is this function, effectively allowing to create nested tables on
the fly: the fly:
>
local a = vim.defaulttable() >lua
a.b.c = 1
local a = vim.defaulttable()
a.b.c = 1
< <
Parameters: ~ Parameters: ~
@@ -1637,12 +1638,12 @@ pesc({s}) *vim.pesc()*
split({s}, {sep}, {kwargs}) *vim.split()* split({s}, {sep}, {kwargs}) *vim.split()*
Splits a string at each instance of a separator. Splits a string at each instance of a separator.
Examples: > Examples: >lua
split(":aa::b:", ":") => {'','aa','','b',''} split(":aa::b:", ":") --> {'','aa','','b',''}
split("axaby", "ab?") => {'','x','y'} split("axaby", "ab?") --> {'','x','y'}
split("x*yz*o", "*", {plain=true}) => {'x','yz','o'} split("x*yz*o", "*", {plain=true}) --> {'x','yz','o'}
split("|x|y|z|", "|", {trimempty=true}) => {'x', 'y', 'z'} split("|x|y|z|", "|", {trimempty=true}) --> {'x', 'y', 'z'}
< <
Parameters: ~ Parameters: ~
@@ -1695,10 +1696,11 @@ tbl_contains({t}, {value}) *vim.tbl_contains()*
tbl_count({t}) *vim.tbl_count()* tbl_count({t}) *vim.tbl_count()*
Counts the number of non-nil values in table `t`. Counts the number of non-nil values in table `t`.
>
vim.tbl_count({ a=1, b=2 }) => 2 >lua
vim.tbl_count({ 1, 2 }) => 2
vim.tbl_count({ a=1, b=2 }) --> 2
vim.tbl_count({ 1, 2 }) --> 2
< <
Parameters: ~ Parameters: ~
@@ -1771,7 +1773,7 @@ tbl_get({o}, {...}) *vim.tbl_get()*
Index into a table (first argument) via string keys passed as subsequent Index into a table (first argument) via string keys passed as subsequent
arguments. Return `nil` if the key does not exist. arguments. Return `nil` if the key does not exist.
Examples: > Examples: >lua
vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true
vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil
@@ -1858,7 +1860,7 @@ trim({s}) *vim.trim()*
validate({opt}) *vim.validate()* validate({opt}) *vim.validate()*
Validates a parameter specification (types and values). Validates a parameter specification (types and values).
Usage example: > Usage example: >lua
function user.new(name, age, hobbies) function user.new(name, age, hobbies)
vim.validate{ vim.validate{
@@ -1870,25 +1872,25 @@ validate({opt}) *vim.validate()*
end end
< <
Examples with explicit argument values (can be run directly): > Examples with explicit argument values (can be run directly): >lua
vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}} vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}}
=> NOP (success) --> NOP (success)
vim.validate{arg1={1, 'table'}} vim.validate{arg1={1, 'table'}}
=> error('arg1: expected table, got number') --> error('arg1: expected table, got number')
vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}} vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}}
=> error('arg1: expected even number, got 3') --> error('arg1: expected even number, got 3')
< <
If multiple types are valid they can be given as a list. > If multiple types are valid they can be given as a list. >lua
vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}} vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}}
=> NOP (success) --> NOP (success)
vim.validate{arg1={1, {'string', table'}}} vim.validate{arg1={1, {'string', table'}}}
=> error('arg1: expected string|table, got number') --> error('arg1: expected string|table, got number')
< <
Parameters: ~ Parameters: ~
@@ -1957,7 +1959,7 @@ Lua module: ui *lua-ui*
input({opts}, {on_confirm}) *vim.ui.input()* input({opts}, {on_confirm}) *vim.ui.input()*
Prompts the user for input Prompts the user for input
Example: > Example: >lua
vim.ui.input({ prompt = 'Enter value for shiftwidth: ' }, function(input) vim.ui.input({ prompt = 'Enter value for shiftwidth: ' }, function(input)
vim.o.shiftwidth = tonumber(input) vim.o.shiftwidth = tonumber(input)
@@ -1982,7 +1984,7 @@ input({opts}, {on_confirm}) *vim.ui.input()*
select({items}, {opts}, {on_choice}) *vim.ui.select()* select({items}, {opts}, {on_choice}) *vim.ui.select()*
Prompts the user to pick a single item from a collection of entries Prompts the user to pick a single item from a collection of entries
Example: > Example: >lua
vim.ui.select({ 'tabs', 'spaces' }, { vim.ui.select({ 'tabs', 'spaces' }, {
prompt = 'Select tabs or spaces:', prompt = 'Select tabs or spaces:',
@@ -2045,7 +2047,7 @@ add({filetypes}) *vim.filetype.add()*
See $VIMRUNTIME/lua/vim/filetype.lua for more examples. See $VIMRUNTIME/lua/vim/filetype.lua for more examples.
Example: > Example: >lua
vim.filetype.add({ vim.filetype.add({
extension = { extension = {
@@ -2081,7 +2083,7 @@ add({filetypes}) *vim.filetype.add()*
}) })
< <
To add a fallback match on contents, use > To add a fallback match on contents, use >lua
vim.filetype.add { vim.filetype.add {
pattern = { pattern = {
@@ -2120,19 +2122,20 @@ match({args}) *vim.filetype.match()*
Each of the three options is specified using a key to the single argument Each of the three options is specified using a key to the single argument
of this function. Example: of this function. Example:
>
-- Using a buffer number >lua
vim.filetype.match({ buf = 42 })
-- Override the filename of the given buffer -- Using a buffer number
vim.filetype.match({ buf = 42, filename = 'foo.c' }) vim.filetype.match({ buf = 42 })
-- Using a filename without a buffer -- Override the filename of the given buffer
vim.filetype.match({ filename = 'main.lua' }) vim.filetype.match({ buf = 42, filename = 'foo.c' })
-- Using file contents -- Using a filename without a buffer
vim.filetype.match({ contents = {'#!/usr/bin/env bash'} }) vim.filetype.match({ filename = 'main.lua' })
-- Using file contents
vim.filetype.match({ contents = {'#!/usr/bin/env bash'} })
< <
Parameters: ~ Parameters: ~
@@ -2162,7 +2165,7 @@ match({args}) *vim.filetype.match()*
Lua module: keymap *lua-keymap* Lua module: keymap *lua-keymap*
del({modes}, {lhs}, {opts}) *vim.keymap.del()* del({modes}, {lhs}, {opts}) *vim.keymap.del()*
Remove an existing mapping. Examples: > Remove an existing mapping. Examples: >lua
vim.keymap.del('n', 'lhs') vim.keymap.del('n', 'lhs')
@@ -2178,7 +2181,7 @@ del({modes}, {lhs}, {opts}) *vim.keymap.del()*
|vim.keymap.set()| |vim.keymap.set()|
set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()* set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()*
Add a new |mapping|. Examples: > Add a new |mapping|. Examples: >lua
-- Can add mapping to Lua functions -- Can add mapping to Lua functions
vim.keymap.set('n', 'lhs', function() print("real lua function") end) vim.keymap.set('n', 'lhs', function() print("real lua function") end)
@@ -2197,14 +2200,14 @@ set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()*
vim.keymap.set('n', '[%', '<Plug>(MatchitNormalMultiBackward)') vim.keymap.set('n', '[%', '<Plug>(MatchitNormalMultiBackward)')
< <
Note that in a mapping like: > Note that in a mapping like: >lua
vim.keymap.set('n', 'asdf', require('jkl').my_fun) vim.keymap.set('n', 'asdf', require('jkl').my_fun)
< <
the `require('jkl')` gets evaluated during this call in order to access the function. If you the `require('jkl')` gets evaluated during this call in order to access the function. If you
want to avoid this cost at startup you can wrap it in a function, for want to avoid this cost at startup you can wrap it in a function, for
example: > example: >lua
vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end) vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end)
< <
@@ -2302,8 +2305,8 @@ find({names}, {opts}) *vim.fs.find()*
number of matches. number of matches.
Return: ~ Return: ~
(table) The normalized paths |vim.fs.normalize()| of all matching (table) Normalized paths |vim.fs.normalize()| of all matching files or
files or directories directories
normalize({path}) *vim.fs.normalize()* normalize({path}) *vim.fs.normalize()*
Normalize a path to a standard format. A tilde (~) character at the Normalize a path to a standard format. A tilde (~) character at the
@@ -2311,16 +2314,16 @@ normalize({path}) *vim.fs.normalize()*
backslash (\) characters are converted to forward slashes (/). Environment backslash (\) characters are converted to forward slashes (/). Environment
variables are also expanded. variables are also expanded.
Examples: > Examples: >lua
vim.fs.normalize('C:\Users\jdoe') vim.fs.normalize('C:\Users\jdoe')
=> 'C:/Users/jdoe' --> 'C:/Users/jdoe'
vim.fs.normalize('~/src/neovim') vim.fs.normalize('~/src/neovim')
=> '/home/jdoe/src/neovim' --> '/home/jdoe/src/neovim'
vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim') vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim')
=> '/Users/jdoe/.config/nvim/init.vim' --> '/Users/jdoe/.config/nvim/init.vim'
< <
Parameters: ~ Parameters: ~
@@ -2332,7 +2335,7 @@ normalize({path}) *vim.fs.normalize()*
parents({start}) *vim.fs.parents()* parents({start}) *vim.fs.parents()*
Iterate over all the parents of the given file or directory. Iterate over all the parents of the given file or directory.
Example: > Example: >lua
local root_dir local root_dir
for dir in vim.fs.parents(vim.api.nvim_buf_get_name(0)) do for dir in vim.fs.parents(vim.api.nvim_buf_get_name(0)) do

6
runtime/doc/treesitter.txt
View File

@@ -605,7 +605,7 @@ start({bufnr}, {lang}) *start()*
required for some plugins. In this case, add `vim.bo.syntax = 'on'` after required for some plugins. In this case, add `vim.bo.syntax = 'on'` after
the call to `start`. the call to `start`.
Example: > Example: >lua
vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex', vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex',
callback = function(args) callback = function(args)
@@ -770,7 +770,7 @@ Query:iter_captures({self}, {node}, {source}, {start}, {stop})
The iterator returns three values: a numeric id identifying the capture, The iterator returns three values: a numeric id identifying the capture,
the captured node, and metadata from any directives processing the match. the captured node, and metadata from any directives processing the match.
The following example shows how to get captures by name: > The following example shows how to get captures by name: >lua
for id, node, metadata in query:iter_captures(tree:root(), bufnr, first, last) do for id, node, metadata in query:iter_captures(tree:root(), bufnr, first, last) do
local name = query.captures[id] -- name of the capture in the query local name = query.captures[id] -- name of the capture in the query
@@ -802,7 +802,7 @@ Query:iter_matches({self}, {node}, {source}, {start}, {stop})
(1-based) index of the pattern in the query, a table mapping capture (1-based) index of the pattern in the query, a table mapping capture
indices to nodes, and metadata from any directives processing the match. indices to nodes, and metadata from any directives processing the match.
If the query has more than one pattern, the capture table might be sparse If the query has more than one pattern, the capture table might be sparse
and e.g. `pairs()` method should be used over `ipairs` . Here is an example iterating over all captures in every match: > and e.g. `pairs()` method should be used over `ipairs` . Here is an example iterating over all captures in every match: >lua
for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, first, last) do for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, first, last) do
for id, node in pairs(match) do for id, node in pairs(match) do

6
runtime/lua/vim/_editor.lua
View File

@@ -123,7 +123,7 @@ do
--- (such as the |TUI|) pastes text into the editor. --- (such as the |TUI|) pastes text into the editor.
--- ---
--- Example: To remove ANSI color codes when pasting: --- Example: To remove ANSI color codes when pasting:
--- <pre> --- <pre>lua
--- vim.paste = (function(overridden) --- vim.paste = (function(overridden)
--- return function(lines, phase) --- return function(lines, phase)
--- for i,line in ipairs(lines) do --- for i,line in ipairs(lines) do
@@ -280,7 +280,7 @@ end
--- command. --- command.
--- ---
--- Example: --- Example:
--- <pre> --- <pre>lua
--- vim.cmd('echo 42') --- vim.cmd('echo 42')
--- vim.cmd([[ --- vim.cmd([[
--- augroup My_group --- augroup My_group
@@ -746,7 +746,7 @@ end
---Prints given arguments in human-readable format. ---Prints given arguments in human-readable format.
---Example: ---Example:
---<pre> ---<pre>lua
--- -- Print highlight group Normal and store it's contents in a variable. --- -- Print highlight group Normal and store it's contents in a variable.
--- local hl_normal = vim.pretty_print(vim.api.nvim_get_hl_by_name("Normal", true)) --- local hl_normal = vim.pretty_print(vim.api.nvim_get_hl_by_name("Normal", true))
---</pre> ---</pre>

26
runtime/lua/vim/diagnostic.lua
View File

@@ -579,12 +579,12 @@ end
--- followed by namespace configuration, and finally global configuration. --- followed by namespace configuration, and finally global configuration.
--- ---
--- For example, if a user enables virtual text globally with --- For example, if a user enables virtual text globally with
--- <pre> --- <pre>lua
--- vim.diagnostic.config({ virtual_text = true }) --- vim.diagnostic.config({ virtual_text = true })
--- </pre> --- </pre>
--- ---
--- and a diagnostic producer sets diagnostics with --- and a diagnostic producer sets diagnostics with
--- <pre> --- <pre>lua
--- vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false }) --- vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false })
--- </pre> --- </pre>
--- ---
@@ -621,13 +621,13 @@ end
--- * format: (function) A function that takes a diagnostic as input and --- * format: (function) A function that takes a diagnostic as input and
--- returns a string. The return value is the text used to display --- returns a string. The return value is the text used to display
--- the diagnostic. Example: --- the diagnostic. Example:
--- <pre> --- <pre>lua
--- function(diagnostic) --- function(diagnostic)
--- if diagnostic.severity == vim.diagnostic.severity.ERROR then --- if diagnostic.severity == vim.diagnostic.severity.ERROR then
--- return string.format("E: %s", diagnostic.message) --- return string.format("E: %s", diagnostic.message)
--- end
--- return diagnostic.message
--- end --- end
--- return diagnostic.message
--- end
--- </pre> --- </pre>
--- - signs: (default true) Use signs for diagnostics. Options: --- - signs: (default true) Use signs for diagnostics. Options:
--- * severity: Only show signs for diagnostics matching the given severity --- * severity: Only show signs for diagnostics matching the given severity
@@ -1577,11 +1577,11 @@ end
--- ---
--- This can be parsed into a diagnostic |diagnostic-structure| --- This can be parsed into a diagnostic |diagnostic-structure|
--- with: --- with:
--- <pre> --- <pre>lua
--- local s = "WARNING filename:27:3: Variable 'foo' does not exist" --- local s = "WARNING filename:27:3: Variable 'foo' does not exist"
--- local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$" --- local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
--- local groups = { "severity", "lnum", "col", "message" } --- local groups = { "severity", "lnum", "col", "message" }
--- vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN }) --- vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN })
--- </pre> --- </pre>
--- ---
---@param str string String to parse diagnostics from. ---@param str string String to parse diagnostics from.

6
runtime/lua/vim/filetype.lua
View File

@@ -2308,7 +2308,7 @@ end
--- See $VIMRUNTIME/lua/vim/filetype.lua for more examples. --- See $VIMRUNTIME/lua/vim/filetype.lua for more examples.
--- ---
--- Example: --- Example:
--- <pre> --- <pre>lua
--- vim.filetype.add({ --- vim.filetype.add({
--- extension = { --- extension = {
--- foo = 'fooscript', --- foo = 'fooscript',
@@ -2344,7 +2344,7 @@ end
--- </pre> --- </pre>
--- ---
--- To add a fallback match on contents, use --- To add a fallback match on contents, use
--- <pre> --- <pre>lua
--- vim.filetype.add { --- vim.filetype.add {
--- pattern = { --- pattern = {
--- ['.*'] = { --- ['.*'] = {
@@ -2456,7 +2456,7 @@ end
--- Each of the three options is specified using a key to the single argument of this function. --- Each of the three options is specified using a key to the single argument of this function.
--- Example: --- Example:
--- ---
--- <pre> --- <pre>lua
--- -- Using a buffer number --- -- Using a buffer number
--- vim.filetype.match({ buf = 42 }) --- vim.filetype.match({ buf = 42 })
--- ---

13
runtime/lua/vim/fs.lua
View File

@@ -3,7 +3,7 @@ local M = {}
--- Iterate over all the parents of the given file or directory. --- Iterate over all the parents of the given file or directory.
--- ---
--- Example: --- Example:
--- <pre> --- <pre>lua
--- local root_dir --- local root_dir
--- for dir in vim.fs.parents(vim.api.nvim_buf_get_name(0)) do --- for dir in vim.fs.parents(vim.api.nvim_buf_get_name(0)) do
--- if vim.fn.isdirectory(dir .. "/.git") == 1 then --- if vim.fn.isdirectory(dir .. "/.git") == 1 then
@@ -98,8 +98,7 @@ end
--- - limit (number, default 1): Stop the search after --- - limit (number, default 1): Stop the search after
--- finding this many matches. Use `math.huge` to --- finding this many matches. Use `math.huge` to
--- place no limit on the number of matches. --- place no limit on the number of matches.
--- ---@return (table) Normalized paths |vim.fs.normalize()| of all matching files or directories
---@return (table) The normalized paths |vim.fs.normalize()| of all matching files or directories
function M.find(names, opts) function M.find(names, opts)
opts = opts or {} opts = opts or {}
vim.validate({ vim.validate({
@@ -214,15 +213,15 @@ end
--- variables are also expanded. --- variables are also expanded.
--- ---
--- Examples: --- Examples:
--- <pre> --- <pre>lua
--- vim.fs.normalize('C:\\Users\\jdoe') --- vim.fs.normalize('C:\\Users\\jdoe')
--- => 'C:/Users/jdoe' --- --> 'C:/Users/jdoe'
--- ---
--- vim.fs.normalize('~/src/neovim') --- vim.fs.normalize('~/src/neovim')
--- => '/home/jdoe/src/neovim' --- --> '/home/jdoe/src/neovim'
--- ---
--- vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim') --- vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim')
--- => '/Users/jdoe/.config/nvim/init.vim' --- --> '/Users/jdoe/.config/nvim/init.vim'
--- </pre> --- </pre>
--- ---
---@param path (string) Path to normalize ---@param path (string) Path to normalize

8
runtime/lua/vim/keymap.lua
View File

@@ -2,7 +2,7 @@ local keymap = {}
--- Add a new |mapping|. --- Add a new |mapping|.
--- Examples: --- Examples:
--- <pre> --- <pre>lua
--- -- Can add mapping to Lua functions --- -- Can add mapping to Lua functions
--- vim.keymap.set('n', 'lhs', function() print("real lua function") end) --- vim.keymap.set('n', 'lhs', function() print("real lua function") end)
--- ---
@@ -21,13 +21,13 @@ local keymap = {}
--- </pre> --- </pre>
--- ---
--- Note that in a mapping like: --- Note that in a mapping like:
--- <pre> --- <pre>lua
--- vim.keymap.set('n', 'asdf', require('jkl').my_fun) --- vim.keymap.set('n', 'asdf', require('jkl').my_fun)
--- </pre> --- </pre>
--- ---
--- the ``require('jkl')`` gets evaluated during this call in order to access the function. --- the ``require('jkl')`` gets evaluated during this call in order to access the function.
--- If you want to avoid this cost at startup you can wrap it in a function, for example: --- If you want to avoid this cost at startup you can wrap it in a function, for example:
--- <pre> --- <pre>lua
--- vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end) --- vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end)
--- </pre> --- </pre>
--- ---
@@ -93,7 +93,7 @@ end
--- Remove an existing mapping. --- Remove an existing mapping.
--- Examples: --- Examples:
--- <pre> --- <pre>lua
--- vim.keymap.del('n', 'lhs') --- vim.keymap.del('n', 'lhs')
--- ---
--- vim.keymap.del({'n', 'i', 'v'}, '<leader>w', { buffer = 5 }) --- vim.keymap.del({'n', 'i', 'v'}, '<leader>w', { buffer = 5 })

8
runtime/lua/vim/lsp.lua
View File

@@ -813,8 +813,7 @@ end
--- Attaches the current buffer to the client. --- Attaches the current buffer to the client.
--- ---
--- Example: --- Example:
--- --- <pre>lua
--- <pre>
--- vim.lsp.start({ --- vim.lsp.start({
--- name = 'my-server-name', --- name = 'my-server-name',
--- cmd = {'name-of-language-server-executable'}, --- cmd = {'name-of-language-server-executable'},
@@ -1754,8 +1753,7 @@ end
--- ---
--- You can also use the `stop()` function on a |vim.lsp.client| object. --- You can also use the `stop()` function on a |vim.lsp.client| object.
--- To stop all clients: --- To stop all clients:
--- --- <pre>lua
--- <pre>
--- vim.lsp.stop_client(vim.lsp.get_active_clients()) --- vim.lsp.stop_client(vim.lsp.get_active_clients())
--- </pre> --- </pre>
--- ---
@@ -2239,7 +2237,7 @@ end
---@param fn function Function to run on each client attached to buffer ---@param fn function Function to run on each client attached to buffer
--- {bufnr}. The function takes the client, client ID, and --- {bufnr}. The function takes the client, client ID, and
--- buffer number as arguments. Example: --- buffer number as arguments. Example:
--- <pre> --- <pre>lua
--- vim.lsp.for_each_buffer_client(0, function(client, client_id, bufnr) --- vim.lsp.for_each_buffer_client(0, function(client, client_id, bufnr)
--- print(vim.inspect(client)) --- print(vim.inspect(client))
--- end) --- end)

19
runtime/lua/vim/lsp/buf.lua
View File

@@ -162,11 +162,11 @@ end
--- Predicate used to filter clients. Receives a client as argument and must return a --- Predicate used to filter clients. Receives a client as argument and must return a
--- boolean. Clients matching the predicate are included. Example: --- boolean. Clients matching the predicate are included. Example:
--- ---
--- <pre> --- <pre>lua
--- -- Never request typescript-language-server for formatting --- -- Never request typescript-language-server for formatting
--- vim.lsp.buf.format { --- vim.lsp.buf.format {
--- filter = function(client) return client.name ~= "tsserver" end --- filter = function(client) return client.name ~= "tsserver" end
--- } --- }
--- </pre> --- </pre>
--- ---
--- - async boolean|nil --- - async boolean|nil
@@ -555,11 +555,10 @@ end
--- Send request to the server to resolve document highlights for the current --- Send request to the server to resolve document highlights for the current
--- text document position. This request can be triggered by a key mapping or --- text document position. This request can be triggered by a key mapping or
--- by events such as `CursorHold`, e.g.: --- by events such as `CursorHold`, e.g.:
--- --- <pre>vim
--- <pre> --- autocmd CursorHold <buffer> lua vim.lsp.buf.document_highlight()
--- autocmd CursorHold <buffer> lua vim.lsp.buf.document_highlight() --- autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight()
--- autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight() --- autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references()
--- autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references()
--- </pre> --- </pre>
--- ---
--- Note: Usage of |vim.lsp.buf.document_highlight()| requires the following highlight groups --- Note: Usage of |vim.lsp.buf.document_highlight()| requires the following highlight groups

3
runtime/lua/vim/lsp/codelens.lua
View File

@@ -241,7 +241,8 @@ end
--- ---
--- It is recommended to trigger this using an autocmd or via keymap. --- It is recommended to trigger this using an autocmd or via keymap.
--- ---
--- <pre> --- Example:
--- <pre>vim
--- autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh() --- autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh()
--- </pre> --- </pre>
--- ---

2
runtime/lua/vim/lsp/diagnostic.lua
View File

@@ -150,7 +150,7 @@ end
--- ---
--- See |vim.diagnostic.config()| for configuration options. Handler-specific --- See |vim.diagnostic.config()| for configuration options. Handler-specific
--- configuration can be set using |vim.lsp.with()|: --- configuration can be set using |vim.lsp.with()|:
--- <pre> --- <pre>lua
--- vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with( --- vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
--- vim.lsp.diagnostic.on_publish_diagnostics, { --- vim.lsp.diagnostic.on_publish_diagnostics, {
--- -- Enable underline, use default values --- -- Enable underline, use default values

32
runtime/lua/vim/lsp/handlers.lua
View File

@@ -313,15 +313,15 @@ M['textDocument/completion'] = function(_, result, _, _)
end end
--- |lsp-handler| for the method "textDocument/hover" --- |lsp-handler| for the method "textDocument/hover"
--- <pre> --- <pre>lua
--- vim.lsp.handlers["textDocument/hover"] = vim.lsp.with( --- vim.lsp.handlers["textDocument/hover"] = vim.lsp.with(
--- vim.lsp.handlers.hover, { --- vim.lsp.handlers.hover, {
--- -- Use a sharp border with `FloatBorder` highlights --- -- Use a sharp border with `FloatBorder` highlights
--- border = "single", --- border = "single",
--- -- add the title in hover float window --- -- add the title in hover float window
--- title = "hover" --- title = "hover"
--- } --- }
--- ) --- )
--- </pre> --- </pre>
---@param config table Configuration table. ---@param config table Configuration table.
--- - border: (default=nil) --- - border: (default=nil)
@@ -399,13 +399,13 @@ M['textDocument/implementation'] = location_handler
--- |lsp-handler| for the method "textDocument/signatureHelp". --- |lsp-handler| for the method "textDocument/signatureHelp".
--- The active parameter is highlighted with |hl-LspSignatureActiveParameter|. --- The active parameter is highlighted with |hl-LspSignatureActiveParameter|.
--- <pre> --- <pre>lua
--- vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with( --- vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with(
--- vim.lsp.handlers.signature_help, { --- vim.lsp.handlers.signature_help, {
--- -- Use a sharp border with `FloatBorder` highlights --- -- Use a sharp border with `FloatBorder` highlights
--- border = "single" --- border = "single"
--- } --- }
--- ) --- )
--- </pre> --- </pre>
---@param config table Configuration table. ---@param config table Configuration table.
--- - border: (default=nil) --- - border: (default=nil)

36
runtime/lua/vim/shared.lua
View File

@@ -102,11 +102,11 @@ end
--- Splits a string at each instance of a separator. --- Splits a string at each instance of a separator.
--- ---
--- Examples: --- Examples:
--- <pre> --- <pre>lua
--- split(":aa::b:", ":") => {'','aa','','b',''} --- split(":aa::b:", ":") --> {'','aa','','b',''}
--- split("axaby", "ab?") => {'','x','y'} --- split("axaby", "ab?") --> {'','x','y'}
--- split("x*yz*o", "*", {plain=true}) => {'x','yz','o'} --- split("x*yz*o", "*", {plain=true}) --> {'x','yz','o'}
--- split("|x|y|z|", "|", {trimempty=true}) => {'x', 'y', 'z'} --- split("|x|y|z|", "|", {trimempty=true}) --> {'x', 'y', 'z'}
--- </pre> --- </pre>
--- ---
---@see |vim.gsplit()| ---@see |vim.gsplit()|
@@ -383,7 +383,7 @@ end
--- Return `nil` if the key does not exist. --- Return `nil` if the key does not exist.
--- ---
--- Examples: --- Examples:
--- <pre> --- <pre>lua
--- vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true --- vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true
--- vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil --- vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil
--- </pre> --- </pre>
@@ -495,9 +495,9 @@ end
--- Counts the number of non-nil values in table `t`. --- Counts the number of non-nil values in table `t`.
--- ---
--- <pre> --- <pre>lua
--- vim.tbl_count({ a=1, b=2 }) => 2 --- vim.tbl_count({ a=1, b=2 }) --> 2
--- vim.tbl_count({ 1, 2 }) => 2 --- vim.tbl_count({ 1, 2 }) --> 2
--- </pre> --- </pre>
--- ---
---@see https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua ---@see https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua
@@ -571,7 +571,7 @@ end
--- Validates a parameter specification (types and values). --- Validates a parameter specification (types and values).
--- ---
--- Usage example: --- Usage example:
--- <pre> --- <pre>lua
--- function user.new(name, age, hobbies) --- function user.new(name, age, hobbies)
--- vim.validate{ --- vim.validate{
--- name={name, 'string'}, --- name={name, 'string'},
@@ -583,24 +583,24 @@ end
--- </pre> --- </pre>
--- ---
--- Examples with explicit argument values (can be run directly): --- Examples with explicit argument values (can be run directly):
--- <pre> --- <pre>lua
--- vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}} --- vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}}
--- => NOP (success) --- --> NOP (success)
--- ---
--- vim.validate{arg1={1, 'table'}} --- vim.validate{arg1={1, 'table'}}
--- => error('arg1: expected table, got number') --- --> error('arg1: expected table, got number')
--- ---
--- vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}} --- vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}}
--- => error('arg1: expected even number, got 3') --- --> error('arg1: expected even number, got 3')
--- </pre> --- </pre>
--- ---
--- If multiple types are valid they can be given as a list. --- If multiple types are valid they can be given as a list.
--- <pre> --- <pre>lua
--- vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}} --- vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}}
--- => NOP (success) --- --> NOP (success)
--- ---
--- vim.validate{arg1={1, {'string', table'}}} --- vim.validate{arg1={1, {'string', table'}}}
--- => error('arg1: expected string|table, got number') --- --> error('arg1: expected string|table, got number')
--- ---
--- </pre> --- </pre>
--- ---
@@ -735,7 +735,7 @@ end
--- If {create} is `nil`, this will create a defaulttable whose constructor function is --- If {create} is `nil`, this will create a defaulttable whose constructor function is
--- this function, effectively allowing to create nested tables on the fly: --- this function, effectively allowing to create nested tables on the fly:
--- ---
--- <pre> --- <pre>lua
--- local a = vim.defaulttable() --- local a = vim.defaulttable()
--- a.b.c = 1 --- a.b.c = 1
--- </pre> --- </pre>

2
runtime/lua/vim/treesitter.lua
View File

@@ -313,7 +313,7 @@ end
--- 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: --- Example:
--- <pre> --- <pre>lua
--- vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex', --- vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex',
--- callback = function(args) --- callback = function(args)
--- vim.treesitter.start(args.buf, 'latex') --- vim.treesitter.start(args.buf, 'latex')

4
runtime/lua/vim/treesitter/query.lua
View File

@@ -549,7 +549,7 @@ end
--- The iterator returns three values: a numeric id identifying the capture, --- The iterator returns three values: a numeric id identifying the capture,
--- the captured node, and metadata from any directives processing the match. --- the captured node, and metadata from any directives processing the match.
--- The following example shows how to get captures by name: --- The following example shows how to get captures by name:
--- <pre> --- <pre>lua
--- for id, node, metadata in query:iter_captures(tree:root(), bufnr, first, last) do --- for id, node, metadata in query:iter_captures(tree:root(), bufnr, first, last) do
--- local name = query.captures[id] -- name of the capture in the query --- local name = query.captures[id] -- name of the capture in the query
--- -- typically useful info about the node: --- -- typically useful info about the node:
@@ -603,7 +603,7 @@ end
--- If the query has more than one pattern, the capture table might be sparse --- If the query has more than one pattern, the capture table might be sparse
--- and e.g. `pairs()` method should be used over `ipairs`. --- and e.g. `pairs()` method should be used over `ipairs`.
--- Here is an example iterating over all captures in every match: --- Here is an example iterating over all captures in every match:
--- <pre> --- <pre>lua
--- for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, first, last) do --- for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, first, last) do
--- for id, node in pairs(match) do --- for id, node in pairs(match) do
--- local name = query.captures[id] --- local name = query.captures[id]

4
runtime/lua/vim/ui.lua
View File

@@ -21,7 +21,7 @@ local M = {}
--- ---
--- ---
--- Example: --- Example:
--- <pre> --- <pre>lua
--- vim.ui.select({ 'tabs', 'spaces' }, { --- vim.ui.select({ 'tabs', 'spaces' }, {
--- prompt = 'Select tabs or spaces:', --- prompt = 'Select tabs or spaces:',
--- format_item = function(item) --- format_item = function(item)
@@ -78,7 +78,7 @@ end
--- `nil` if the user aborted the dialog. --- `nil` if the user aborted the dialog.
--- ---
--- Example: --- Example:
--- <pre> --- <pre>lua
--- vim.ui.input({ prompt = 'Enter value for shiftwidth: ' }, function(input) --- vim.ui.input({ prompt = 'Enter value for shiftwidth: ' }, function(input)
--- vim.o.shiftwidth = tonumber(input) --- vim.o.shiftwidth = tonumber(input)
--- end) --- end)

7
scripts/gen_vimdoc.py
View File

@@ -496,7 +496,12 @@ def render_node(n, text, prefix='', indent='', width=text_width - indentation,
if n.nodeName == 'preformatted': if n.nodeName == 'preformatted':
o = get_text(n, preformatted=True) o = get_text(n, preformatted=True)
ensure_nl = '' if o[-1] == '\n' else '\n' ensure_nl = '' if o[-1] == '\n' else '\n'
text += '>{}{}\n<'.format(ensure_nl, o) if o[0:4] == 'lua\n':
text += '>lua{}{}\n<'.format(ensure_nl, o[3:-1])
elif o[0:4] == 'vim\n':
text += '>vim{}{}\n<'.format(ensure_nl, o[3:-1])
else:
text += '>{}{}\n<'.format(ensure_nl, o)
elif is_inline(n): elif is_inline(n):
text = doc_wrap(get_text(n), indent=indent, width=width) text = doc_wrap(get_text(n), indent=indent, width=width)

21
src/nvim/api/autocmd.c
View File

@@ -47,7 +47,7 @@ static int64_t next_autocmd_id = 1;
/// Get all autocommands that match the corresponding {opts}. /// Get all autocommands that match the corresponding {opts}.
/// ///
/// These examples will get autocommands matching ALL the given criteria: /// These examples will get autocommands matching ALL the given criteria:
/// <pre> /// <pre>lua
/// -- Matches all criteria /// -- Matches all criteria
/// autocommands = vim.api.nvim_get_autocmds({ /// autocommands = vim.api.nvim_get_autocmds({
/// group = "MyGroup", /// group = "MyGroup",
@@ -367,7 +367,7 @@ cleanup:
/// triggers: a callback function (Lua or Vimscript), or a command (like regular autocommands). /// triggers: a callback function (Lua or Vimscript), or a command (like regular autocommands).
/// ///
/// Example using callback: /// Example using callback:
/// <pre> /// <pre>lua
/// -- Lua function /// -- Lua function
/// local myluafun = function() print("This buffer enters") end /// local myluafun = function() print("This buffer enters") end
/// ///
@@ -383,8 +383,7 @@ cleanup:
/// Lua functions receive a table with information about the autocmd event as an argument. To use /// Lua functions receive a table with information about the autocmd event as an argument. To use
/// a function which itself accepts another (optional) parameter, wrap the function /// a function which itself accepts another (optional) parameter, wrap the function
/// in a lambda: /// in a lambda:
/// /// <pre>lua
/// <pre>
/// -- Lua function with an optional parameter. /// -- Lua function with an optional parameter.
/// -- The autocmd callback would pass a table as argument but this /// -- The autocmd callback would pass a table as argument but this
/// -- function expects number|nil /// -- function expects number|nil
@@ -397,7 +396,7 @@ cleanup:
/// </pre> /// </pre>
/// ///
/// Example using command: /// Example using command:
/// <pre> /// <pre>lua
/// vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { /// vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
/// pattern = {"*.c", "*.h"}, /// pattern = {"*.c", "*.h"},
/// command = "echo 'Entering a C or C++ file'", /// command = "echo 'Entering a C or C++ file'",
@@ -405,7 +404,7 @@ cleanup:
/// </pre> /// </pre>
/// ///
/// Example values for pattern: /// Example values for pattern:
/// <pre> /// <pre>lua
/// pattern = "*.py" /// pattern = "*.py"
/// pattern = { "*.py", "*.pyi" } /// pattern = { "*.py", "*.pyi" }
/// </pre> /// </pre>
@@ -413,14 +412,14 @@ cleanup:
/// Note: The `pattern` is passed to callbacks and commands as a literal string; environment /// Note: The `pattern` is passed to callbacks and commands as a literal string; environment
/// variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|. /// variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|.
/// Instead, |expand()| such variables explicitly: /// Instead, |expand()| such variables explicitly:
/// <pre> /// <pre>lua
/// pattern = vim.fn.expand("~") .. "/some/path/*.py" /// pattern = vim.fn.expand("~") .. "/some/path/*.py"
/// </pre> /// </pre>
/// ///
/// Example values for event: /// Example values for event:
/// <pre> /// <pre>lua
/// "BufWritePre" /// event = "BufWritePre"
/// {"CursorHold", "BufWritePre", "BufWritePost"} /// event = {"CursorHold", "BufWritePre", "BufWritePost"}
/// </pre> /// </pre>
/// ///
/// @param event (string|array) The event or events to register this autocommand /// @param event (string|array) The event or events to register this autocommand
@@ -703,7 +702,7 @@ cleanup:
/// Create or get an autocommand group |autocmd-groups|. /// Create or get an autocommand group |autocmd-groups|.
/// ///
/// To get an existing group id, do: /// To get an existing group id, do:
/// <pre> /// <pre>lua
/// local id = vim.api.nvim_create_augroup("MyGroup", { /// local id = vim.api.nvim_create_augroup("MyGroup", {
/// clear = false /// clear = false
/// }) /// })

2
src/nvim/api/buffer.c
View File

@@ -84,7 +84,7 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
/// ///
/// Example (Lua): capture buffer updates in a global `events` variable /// Example (Lua): capture buffer updates in a global `events` variable
/// (use "print(vim.inspect(events))" to see its contents): /// (use "print(vim.inspect(events))" to see its contents):
/// <pre> /// <pre>lua
/// events = {} /// events = {}
/// vim.api.nvim_buf_attach(0, false, { /// vim.api.nvim_buf_attach(0, false, {
/// on_lines=function(...) table.insert(events, {...}) end}) /// on_lines=function(...) table.insert(events, {...}) end})

2
src/nvim/api/command.c
View File

@@ -889,7 +889,7 @@ static void build_cmdline_str(char **cmdlinep, exarg_T *eap, CmdParseInfo *cmdin
/// {command} is the replacement text or Lua function to execute. /// {command} is the replacement text or Lua function to execute.
/// ///
/// Example: /// Example:
/// <pre> /// <pre>vim
/// :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {}) /// :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {})
/// :SayHello /// :SayHello
/// Hello world! /// Hello world!

6
src/nvim/api/extmark.c
View File

@@ -255,8 +255,7 @@ ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id,
/// Region can be given as (row,col) tuples, or valid extmark ids (whose /// 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) /// positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1)
/// respectively, thus the following are equivalent: /// respectively, thus the following are equivalent:
/// /// <pre>lua
/// <pre>
/// nvim_buf_get_extmarks(0, my_ns, 0, -1, {}) /// nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
/// nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {}) /// nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {})
/// </pre> /// </pre>
@@ -265,8 +264,7 @@ ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id,
/// with `limit`, to get the first marks prior to a given position.) /// with `limit`, to get the first marks prior to a given position.)
/// ///
/// Example: /// Example:
/// /// <pre>lua
/// <pre>
/// local a = vim.api /// local a = vim.api
/// local pos = a.nvim_win_get_cursor(0) /// local pos = a.nvim_win_get_cursor(0)
/// local ns = a.nvim_create_namespace('my-plugin') /// local ns = a.nvim_create_namespace('my-plugin')

8
src/nvim/api/vim.c
View File

@@ -229,7 +229,7 @@ void nvim_set_hl_ns_fast(Integer ns_id, Error *err)
/// nvim_feedkeys(). /// nvim_feedkeys().
/// ///
/// Example: /// Example:
/// <pre> /// <pre>vim
/// :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true) /// :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true)
/// :call nvim_feedkeys(key, 'n', v:false) /// :call nvim_feedkeys(key, 'n', v:false)
/// </pre> /// </pre>
@@ -1295,7 +1295,7 @@ void nvim_unsubscribe(uint64_t channel_id, String event)
/// "#rrggbb" hexadecimal string. /// "#rrggbb" hexadecimal string.
/// ///
/// Example: /// Example:
/// <pre> /// <pre>vim
/// :echo nvim_get_color_by_name("Pink") /// :echo nvim_get_color_by_name("Pink")
/// :echo nvim_get_color_by_name("#cbcbcb") /// :echo nvim_get_color_by_name("#cbcbcb")
/// </pre> /// </pre>
@@ -1437,12 +1437,12 @@ ArrayOf(Dictionary) nvim_get_keymap(String mode)
/// Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual. /// Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual.
/// ///
/// Example: /// Example:
/// <pre> /// <pre>vim
/// call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true}) /// call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})
/// </pre> /// </pre>
/// ///
/// is equivalent to: /// is equivalent to:
/// <pre> /// <pre>vim
/// nmap <nowait> <Space><NL> <Nop> /// nmap <nowait> <Space><NL> <Nop>
/// </pre> /// </pre>
/// ///

4
src/nvim/api/win_config.c
View File

@@ -55,13 +55,13 @@
/// this should not be used to specify arbitrary WM screen positions. /// this should not be used to specify arbitrary WM screen positions.
/// ///
/// Example (Lua): window-relative float /// Example (Lua): window-relative float
/// <pre> /// <pre>lua
/// vim.api.nvim_open_win(0, false, /// vim.api.nvim_open_win(0, false,
/// {relative='win', row=3, col=3, width=12, height=3}) /// {relative='win', row=3, col=3, width=12, height=3})
/// </pre> /// </pre>
/// ///
/// Example (Lua): buffer-relative float (travels as buffer is scrolled) /// Example (Lua): buffer-relative float (travels as buffer is scrolled)
/// <pre> /// <pre>lua
/// vim.api.nvim_open_win(0, false, /// vim.api.nvim_open_win(0, false,
/// {relative='win', width=12, height=3, bufpos={100,10}}) /// {relative='win', width=12, height=3, bufpos={100,10}})
/// </pre> /// </pre>