docs: api, messages, lsp, trust

gen_vimdoc.lua: In prepare for the upcoming release, comment-out the
"Experimental" warning for prerelease features.

13 files changed, 103 insertions, 86 deletions

diff --git a/runtime/lua/vim/_core/defaults.lua b/runtime/lua/vim/_core/defaults.lua
index e923e8934c..9b9ab01b52 100644
--- a/runtime/lua/vim/_core/defaults.lua
+++ b/runtime/lua/vim/_core/defaults.lua
@@ -445,15 +445,15 @@ do
     end, { expr = true, desc = 'Add empty line below cursor' })
   end
 
-  --- incremental treesitter selection mappings (+ lsp fallback)
+  --- "Incremental selection" mappings (treesitter + LSP fallback).
   do
     vim.keymap.set({ 'x' }, '[n', function()
       require 'vim.treesitter._select'.select_prev(vim.v.count1)
-    end, { desc = 'Select previous treesitter node' })
+    end, { desc = 'Select previous node' })
 
     vim.keymap.set({ 'x' }, ']n', function()
       require 'vim.treesitter._select'.select_next(vim.v.count1)
-    end, { desc = 'Select next treesitter node' })
+    end, { desc = 'Select next node' })
 
     vim.keymap.set({ 'x', 'o' }, 'an', function()
       if vim.treesitter.get_parser(nil, nil, { error = false }) then
@@ -461,7 +461,7 @@ do
       else
         vim.lsp.buf.selection_range(vim.v.count1)
       end
-    end, { desc = 'Select parent treesitter node or outer incremental lsp selections' })
+    end, { desc = 'Select parent (outer) node' })
 
     vim.keymap.set({ 'x', 'o' }, 'in', function()
       if vim.treesitter.get_parser(nil, nil, { error = false }) then
@@ -469,7 +469,7 @@ do
       else
         vim.lsp.buf.selection_range(-vim.v.count1)
       end
-    end, { desc = 'Select child treesitter node or inner incremental lsp selections' })
+    end, { desc = 'Select child (inner) node' })
   end
 end
 
diff --git a/runtime/lua/vim/_core/shared.lua b/runtime/lua/vim/_core/shared.lua
index 1f01b70f2a..da50338d01 100644
--- a/runtime/lua/vim/_core/shared.lua
+++ b/runtime/lua/vim/_core/shared.lua
@@ -360,7 +360,7 @@ local function key_fn(v, key)
   return key and key(v) or v
 end
 
---- Removes duplicate values from a list-like table in-place.
+--- Removes duplicate values from a |lua-list| in-place.
 ---
 --- Only the first occurrence of each value is kept.
 --- The operation is performed in-place and the input table is modified.
@@ -383,6 +383,7 @@ end
 --- -- t is now { {id=1}, {id=2} }
 --- ```
 ---
+--- @since 14
 --- @generic T
 --- @param t T[]
 --- @param key? fun(x: T): any Optional hash function to determine uniqueness of values
@@ -482,8 +483,8 @@ local function upper_bound(t, val, lo, hi, key)
   return lo
 end
 
---- Search for a position in a sorted list {t}
---- where {val} can be inserted while keeping the list sorted.
+--- Search for a position in a sorted |lua-list| {t} where {val} can be inserted while keeping the
+--- list sorted.
 ---
 --- Use {bound} to determine whether to return the first or the last position,
 --- defaults to "lower", i.e., the first position.
@@ -514,6 +515,7 @@ end
 ---   print(t[i]) -- { 3, 3, 3 }
 --- end
 --- ```
+---@since 14
 ---@generic T
 ---@param t T[] A comparable list.
 ---@param val T The value to search.
diff --git a/runtime/lua/vim/_core/ui2.lua b/runtime/lua/vim/_core/ui2.lua
index debd1feac5..c679f2bdde 100644
--- a/runtime/lua/vim/_core/ui2.lua
+++ b/runtime/lua/vim/_core/ui2.lua
@@ -11,7 +11,7 @@
 ---    ---@type 'cmd'|'msg' Default message target, either in the
 ---    ---cmdline or in a separate ephemeral message window.
 ---    ---@type string|table<string, 'cmd'|'msg'|'pager'> Default message target
----    or table mapping |ui-messages| kinds and triggers to a target.
+---    ---or table mapping |ui-messages| kinds and triggers to a target.
 ---    targets = 'cmd',
 ---    timeout = 4000, -- Time a message is visible in the message window.
 ---  },
@@ -32,7 +32,9 @@
 ---
 ---Rather than a |hit-enter-prompt|, messages shown in the cmdline area that do
 ---not fit are appended with a `[+x]` "spill" indicator, where `x` indicates the
----spilled lines. To see the full message, the |g<| command can be used.
+---spilled lines. To see the full message, use either:
+--- - ENTER immediately after a message from interactive |:| cmdline.
+--- - |g<| at any time.
 
 local api = vim.api
 local M = {
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 9b7bec6678..ff05e0a332 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -1703,26 +1703,19 @@ function vim.api.nvim_notify(msg, log_level, opts) end
 --- @return integer # Channel id, or 0 on error
 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 current window.
---- If -1 is provided, a top-level split will be created. `vertical` and `split` are
---- only valid for normal windows, and are used to 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.
+--- Opens a new split window, floating window, or external window.
+---
+--- - Specify `relative` to create a floating window. Floats are drawn over the split layout,
+---   relative to a position in some other window. See `api-floatwin`.
+---   - Floats must specify `width` and `height`.
+--- - Specify `external` to create an external window. External windows are displayed as separate
+---   top-level windows managed by the `ui-multigrid` UI (not Nvim).
+--- - If `relative` and `external` are omitted, a normal "split" window is created.
+---   - The `win` key decides which window to split. If nil or 0, the split will be adjacent to
+---     the current window. If -1, a top-level split will be created.
+---   - Use `vertical` and `split` to control split direction. For `vertical`, the exact direction
+---     is determined by 'splitright' and 'splitbelow'.
+---   - Split windows cannot have `bufpos`, `row`, `col`, `border`, `title`, `footer`.
 ---
 --- 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
@@ -2492,11 +2485,11 @@ function vim.api.nvim_win_is_valid(window) end
 --- @param buffer integer Buffer id
 function vim.api.nvim_win_set_buf(window, buffer) end
 
---- Reconfigures the layout of a window.
+--- Reconfigures the layout and properties of a window.
 ---
---- - Absent (`nil`) keys will not be changed.
---- - `row` / `col` / `relative` must be reconfigured together.
---- - Cannot be used to move the last window in a tabpage to a different one.
+--- - Updates only the given keys; unspecified (`nil`) keys will not be changed.
+--- - Keys `row` / `col` / `relative` must be specified together.
+--- - Cannot move the last window in a tabpage to a different one.
 ---
 --- Example: to convert a floating window to a "normal" split window, specify the `win` field:
 ---
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
index 177c77b8eb..4b532cf34e 100644
--- a/runtime/lua/vim/_meta/options.lua
+++ b/runtime/lua/vim/_meta/options.lua
@@ -3159,6 +3159,7 @@ vim.go.gp = vim.go.grepprg
 ---
 --- ```vim
 ---     highlight Cursor gui=reverse guifg=NONE guibg=NONE
+---     " Note: gui=reverse overrides colors.
 ---     highlight Cursor gui=NONE guifg=bg guibg=fg
 --- ```
 ---
@@ -3240,7 +3241,7 @@ vim.go.gcr = vim.go.guicursor
 ---
 ---
 --- @type string
-vim.o.guifont = "Source Code Pro,DejaVu Sans Mono,Courier New,monospace"
+vim.o.guifont = "DFLT_GFN"
 vim.o.gfn = vim.o.guifont
 vim.go.guifont = vim.o.guifont
 vim.go.gfn = vim.go.guifont
diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua
index 58cdddce48..dec1cfc476 100644
--- a/runtime/lua/vim/_meta/vvars.lua
+++ b/runtime/lua/vim/_meta/vvars.lua
@@ -6,24 +6,26 @@ error('Cannot require a meta file')
 --- @class vim.v
 vim.v = ...
 
---- The list of file arguments passed on the command line at startup.
----
---- Each filename is expanded to an absolute path, so that v:argf
---- remains valid even if the current working directory changes later.
+--- File arguments (expanded to absolute paths) given at startup.
 ---
 --- Unlike `v:argv`, this does not include option arguments
 --- such as `-u`, `--cmd`, or `+cmd`. Unlike `argv()`, it is not
 --- affected by later `:args`, `:argadd`, or plugin modifications.
---- It also handles the `--` separator correctly, including only
---- files specified after it.
 ---
---- This is a read-only snapshot of the original startup file arguments.
+--- Example:
+--- ```
+---   nvim file1.txt +ls -- file2.txt
+---   :echo v:argf
+---   " ['/path/to/cwd/file1.txt', '/path/to/cwd/file2.txt']
+--- ```
 --- @type string[]
 vim.v.argf = ...
 
---- The command line arguments Vim was invoked with.  This is a
---- list of strings.  The first item is the Vim command.
---- See `v:progpath` for the command with full path.
+--- Command line arguments (`-u`, `--cmd`, `+cmd`, …) Nvim was
+--- invoked with.  The first item is the Nvim command.
+---
+--- See `v:progpath` to get the full path to Nvim.
+--- See `v:argf` to get only file args, without other options.
 --- @type string[]
 vim.v.argv = ...
 
diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index 654ab9bf12..1bcfcaffa0 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -243,6 +243,7 @@ end
 --- -- { {id=1}, {id=2} }
 --- ```
 ---
+---@since 14
 ---@param key? fun(...):any Optional hash function to determine uniqueness of values.
 ---@return Iter
 ---@see |vim.list.unique()|
@@ -282,6 +283,7 @@ end
 --- -- error: attempt to flatten a dict-like table
 --- ```
 ---
+---@since 12
 ---@param depth? number Depth to which |list-iterator| should be flattened
 ---                        (defaults to 1)
 ---@return Iter
@@ -331,6 +333,7 @@ end
 --- -- { 6, 12 }
 --- ```
 ---
+---@since 12
 ---@param f fun(...):...:any Mapping function. Takes all values returned from
 ---                      the previous stage in the pipeline as arguments
 ---                      and returns one or more new values, which are used
@@ -399,6 +402,7 @@ end
 ---
 --- For functions with side effects. To modify the values in the iterator, use |Iter:map()|.
 ---
+---@since 12
 ---@param f fun(...) Function to execute for each item in the pipeline.
 ---                  Takes all of the values returned by the previous stage
 ---                  in the pipeline as arguments.
@@ -446,6 +450,7 @@ end
 --- To create a map-like table with arbitrary keys, use |Iter:fold()|.
 ---
 ---
+---@since 12
 ---@return table
 function Iter:totable()
   local t = {}
@@ -498,6 +503,7 @@ end
 ---
 --- Consumes the iterator.
 ---
+--- @since 12
 --- @param delim string Delimiter
 --- @return string
 function Iter:join(delim)
@@ -527,6 +533,7 @@ end
 ---
 ---@generic A
 ---
+---@since 12
 ---@param init A Initial value of the accumulator.
 ---@param f fun(acc:A, ...):A Accumulation function.
 ---@return A
@@ -572,6 +579,7 @@ end
 ---
 --- ```
 ---
+---@since 12
 ---@return any
 function Iter:next()
   if self._peeked then
@@ -606,6 +614,7 @@ end
 ---
 --- ```
 ---
+---@since 12
 ---@return Iter
 function Iter:rev()
   error('rev() requires an array-like table')
@@ -637,6 +646,7 @@ end
 ---
 --- ```
 ---
+---@since 12
 ---@return any
 function Iter:peek()
   if not self._peeked then
@@ -674,6 +684,7 @@ end
 --- -- 12
 ---
 --- ```
+---@since 12
 ---@param f any
 ---@return any
 function Iter:find(f)
@@ -720,6 +731,7 @@ end
 ---
 ---@see |Iter:find()|
 ---
+---@since 12
 ---@param f any
 ---@return any
 ---@diagnostic disable-next-line: unused-local
@@ -769,6 +781,7 @@ end
 --- -- nil
 --- ```
 ---
+---@since 12
 ---@param n integer|fun(...):boolean Number of values to take or a predicate.
 ---@return Iter
 function Iter:take(n)
@@ -828,6 +841,7 @@ end
 --- -- 3
 --- ```
 ---
+---@since 12
 ---@return any
 function Iter:pop()
   error('pop() requires an array-like table')
@@ -858,6 +872,7 @@ end
 ---
 ---@see |Iter:last()|
 ---
+---@since 12
 ---@return any
 function Iter:rpeek()
   error('rpeek() requires an array-like table')
@@ -891,6 +906,7 @@ end
 --- -- 12
 --- ```
 ---
+---@since 12
 ---@param n integer|fun(...):boolean Number of values to skip or a predicate.
 ---@return Iter
 function Iter:skip(n)
@@ -956,6 +972,7 @@ end
 --- -- 3
 --- ```
 ---
+---@since 12
 ---@param n number Number of values to skip.
 ---@return Iter
 ---@diagnostic disable-next-line: unused-local
@@ -993,6 +1010,7 @@ end
 --- -- 3
 --- ```
 ---
+---@since 12
 ---@param n number Index of the value to return. May be negative if the source is a |list-iterator|.
 ---@return any
 function Iter:nth(n)
@@ -1007,6 +1025,7 @@ end
 ---
 --- Equivalent to `:skip(first - 1):rskip(len - last + 1)`.
 ---
+---@since 12
 ---@param first number
 ---@param last number
 ---@return Iter
@@ -1022,6 +1041,7 @@ end
 
 --- Returns true if any of the items in the iterator match the given predicate.
 ---
+---@since 12
 ---@param pred fun(...):boolean Predicate function. Takes all values returned from the previous
 ---                          stage in the pipeline as arguments and returns true if the
 ---                          predicate matches.
@@ -1046,6 +1066,7 @@ end
 
 --- Returns true if all items in the iterator match the given predicate.
 ---
+---@since 12
 ---@param pred fun(...):boolean Predicate function. Takes all values returned from the previous
 ---                          stage in the pipeline as arguments and returns true if the
 ---                          predicate matches.
@@ -1083,6 +1104,7 @@ end
 ---
 --- ```
 ---
+---@since 12
 ---@see |Iter:rpeek()|
 ---
 ---@return any
@@ -1135,6 +1157,7 @@ end
 ---
 --- ```
 ---
+---@since 12
 ---@return Iter
 function Iter:enumerate()
   local i = 0
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
index d1ed9138ea..5aa473968f 100644
--- a/runtime/lua/vim/lsp.lua
+++ b/runtime/lua/vim/lsp.lua
@@ -1046,13 +1046,11 @@ end
 --- ```
 ---
 --- By default asks the server to shutdown, unless stop was requested already for this client (then
---- force-shutdown is attempted, unless `exit_timeout=false`).
+--- force-stop is attempted, unless `exit_timeout=false`).
 ---
 ---@deprecated
 ---@param client_id integer|integer[]|vim.lsp.Client[] id, list of id's, or list of |vim.lsp.Client| objects
----@param force? boolean|integer Whether to shutdown forcefully.
---- If `force` is a number, it will be treated as the time in milliseconds to
---- wait before forcing the shutdown.
+---@param force? boolean|integer See |Client:stop()|
 function lsp.stop_client(client_id, force)
   vim.deprecate('vim.lsp.stop_client()', 'vim.lsp.Client:stop()', '0.13')
   --- @type integer[]|vim.lsp.Client[]
diff --git a/runtime/lua/vim/lsp/client.lua b/runtime/lua/vim/lsp/client.lua
index d98f1c000f..635c2cde76 100644
--- a/runtime/lua/vim/lsp/client.lua
+++ b/runtime/lua/vim/lsp/client.lua
@@ -68,9 +68,11 @@ local all_clients = {}
 --- (default: `true`)
 --- @field detached? boolean
 ---
---- Milliseconds to wait for server to exit cleanly after sending the "shutdown" request before
---- sending kill -15. If set to false, waits indefinitely. If set to true, nvim will kill the
---- server immediately.
+--- Decides if/when to force-stop the server after sending the "shutdown" request. See |Client:stop()|.
+--- Note: when Nvim itself is exiting,
+--- - `false`: Nvim will not force-stop LSP server(s).
+--- - `true`: Nvim will force-stop LSP server(s) that did not comply with the "shutdown" request.
+--- - `number`: Nvim will wait up to `exit_timeout` milliseconds before performing force-stop.
 --- (default: `false`)
 --- @field exit_timeout? integer|boolean
 ---
@@ -156,9 +158,7 @@ local all_clients = {}
 --- Capabilities provided at runtime (after startup).
 --- @field dynamic_capabilities lsp.DynamicCapabilities
 ---
---- Milliseconds to wait for server to exit cleanly after sending the "shutdown" request before
---- sending kill -15. If set to false, waits indefinitely. If set to true, nvim will kill the
---- server immediately.
+--- See [vim.lsp.ClientConfig].
 --- (default: `false`)
 --- @field exit_timeout integer|boolean
 ---
@@ -852,20 +852,19 @@ end
 
 --- Stops a client, optionally with force after a timeout.
 ---
---- By default, it will request the server to shutdown, then force a shutdown
---- if the server has not exited after `self.exit_timeout` milliseconds. If
---- you request to stop a client which has previously been requested to
---- shutdown, it will automatically escalate and force shutdown immediately,
---- regardless of the value of `force` (or `self.exit_timeout` if `nil`).
+--- By default this sends a "shutdown" request to the server, escalating to force-stop if the server
+--- has not exited after `self.exit_timeout` milliseconds (unless `exit_timeout=false`).
+--- Calling stop() on a client that was previously requested to shutdown, will escalate to
+--- force-stop immediately, regardless of `force` (or `self.exit_timeout` if `force=nil`).
 ---
---- Note: Forcing shutdown while a server is busy writing out project or index
---- files can lead to file corruption.
+--- Note: Forcing shutdown while a server is busy writing out project or index files can lead to
+--- file corruption.
 ---
---- @param force? integer|boolean Time in milliseconds to wait before forcing
----                               a shutdown. If false, only request the
----                               server to shutdown, but don't force it. If
----                               true, force a shutdown immediately.
----                               (default: `self.exit_timeout`)
+--- @param force? integer|boolean (default: `self.exit_timeout`) Decides whether to force-stop the server.
+--- - `nil`: Defaults to `exit_timeout` from |vim.lsp.ClientConfig|.
+--- - `true`: Force-stop after "shutdown" request.
+--- - `false`: Do not force-stop after "shutdown" request.
+--- - number: Wait up to `force` milliseconds before force-stop.
 function Client:stop(force)
   validate('force', force, { 'number', 'boolean' }, true)
 
diff --git a/runtime/lua/vim/lsp/completion.lua b/runtime/lua/vim/lsp/completion.lua
index 4910c415d9..e495af4240 100644
--- a/runtime/lua/vim/lsp/completion.lua
+++ b/runtime/lua/vim/lsp/completion.lua
@@ -6,7 +6,7 @@
 ---
 --- Example: activate LSP-driven auto-completion:
 --- ```lua
---- -- Works best with completeopt=noselect.
+--- -- Works best if 'completeopt' has "noselect".
 --- -- Use CTRL-Y to select an item. |complete_CTRL-Y|
 --- vim.cmd[[set completeopt+=menuone,noselect,popup]]
 --- vim.lsp.start({
@@ -1159,15 +1159,14 @@ end
 --- Enables or disables completions from the given language client in the given
 --- buffer. Effects of enabling completions are:
 ---
---- - Calling |vim.lsp.completion.get()| uses the enabled clients to retrieve
----   completion candidates
+--- - Calling |vim.lsp.completion.get()| uses the enabled clients to retrieve completion candidates.
+--- - Selecting a completion item shows a preview popup ("completionItem/resolve") if 'completeopt'
+---   has "popup".
+--- - Accepting a completion item using `<c-y>` applies side effects like expanding snippets,
+---   text edits (e.g. insert import statements) and executing associated commands. This works for
+---   completions triggered via autotrigger, 'omnifunc' or [vim.lsp.completion.get()].
 ---
---- - Accepting a completion candidate using `<c-y>` applies side effects like
----   expanding snippets, text edits (e.g. insert import statements) and
----   executing associated commands. This works for completions triggered via
----   autotrigger, omnifunc or completion.get()
----
---- Example: |lsp-attach| |lsp-completion|
+--- Examples: |lsp-attach| |lsp-completion|
 ---
 --- Note: the behavior of `autotrigger=true` is controlled by the LSP `triggerCharacters` field. You
 --- can override it on LspAttach, see |lsp-autocompletion|.
diff --git a/runtime/lua/vim/pack.lua b/runtime/lua/vim/pack.lua
index c59a9b410a..6d9b8dc9a1 100644
--- a/runtime/lua/vim/pack.lua
+++ b/runtime/lua/vim/pack.lua
@@ -1204,9 +1204,8 @@ end
 --- @field offline? boolean Whether to skip downloading new updates. Default: `false`.
 ---
 --- How to compute a new plugin revision. One of:
----     - "version" (default) - use latest revision matching `version` from plugin specification.
----     - "lockfile" - use revision from the lockfile. Useful for reverting or performing controlled
----       update.
+---   - "version" (default): use latest revision matching `version` from plugin specification.
+---   - "lockfile": use revision from the lockfile. For reverting or performing controlled update.
 --- @field target? string
 
 --- Update plugins
diff --git a/runtime/lua/vim/secure.lua b/runtime/lua/vim/secure.lua
index 784b4d5ff0..9f5463ac98 100644
--- a/runtime/lua/vim/secure.lua
+++ b/runtime/lua/vim/secure.lua
@@ -162,9 +162,10 @@ end
 --- @class vim.trust.opts
 --- @inlinedoc
 ---
---- - `'allow'` to add a file to the trust database and trust it,
---- - `'deny'` to add a file to the trust database and deny it,
---- - `'remove'` to remove file from the trust database
+--- One of:
+---   - `'allow'` to add a file to the trust database and trust it,
+---   - `'deny'` to add a file to the trust database and deny it,
+---   - `'remove'` to remove file from the trust database
 --- @field action 'allow'|'deny'|'remove'
 ---
 --- Path to a file to update. Mutually exclusive with {bufnr}.
diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua
index 7fa954698d..d29e376ef1 100644
--- a/runtime/lua/vim/treesitter/query.lua
+++ b/runtime/lua/vim/treesitter/query.lua
@@ -1193,10 +1193,8 @@ end
 --- parsers.
 ---
 --- If you move the cursor to a capture name ("@foo"), text matching the capture is highlighted
---- with |hl-DiagnosticVirtualTextHint| in the source buffer.
----
---- The query editor is a scratch buffer, use `:write` to save it. You can find example queries
---- at `$VIMRUNTIME/queries/`.
+--- with |hl-DiagnosticVirtualTextHint| in the source buffer. The query editor is a scratch buffer,
+--- use `:write` to save it. You can find example queries at `$VIMRUNTIME/queries/`.
 ---
 --- @param lang? string language to open the query editor for. If omitted, inferred from the current buffer's filetype.
 function M.edit(lang)