From a4290f462ed7dc81e17b09bd27877b106b24b6bd Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Tue, 5 Mar 2024 12:06:15 +0000 Subject: [PATCH] docs(lua): improvements for LSP and Diagnostic --- runtime/doc/diagnostic.txt | 454 ++++++++---------- runtime/doc/lsp.txt | 94 ++-- runtime/doc/lua.txt | 37 +- runtime/lua/vim/_inspector.lua | 11 +- runtime/lua/vim/diagnostic.lua | 371 +++++++------- runtime/lua/vim/lsp.lua | 17 +- runtime/lua/vim/lsp/client.lua | 47 +- runtime/lua/vim/lsp/diagnostic.lua | 2 +- runtime/lua/vim/lsp/semantic_tokens.lua | 2 +- runtime/lua/vim/shared.lua | 14 +- scripts/gen_vimdoc.lua | 15 +- scripts/luacats_grammar.lua | 2 +- .../script/luacats_grammar_spec.lua | 9 + 13 files changed, 568 insertions(+), 507 deletions(-) diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt index 29859f7b05..c61c17c9b0 100644 --- a/runtime/doc/diagnostic.txt +++ b/runtime/doc/diagnostic.txt @@ -367,79 +367,211 @@ Lua module: vim.diagnostic *diagnostic-api* • {user_data}? (`any`) arbitrary data plugins can add • {namespace}? (`integer`) +*vim.diagnostic.GetOpts* + A table with the following keys: + + Fields: ~ + • {namespace}? (`integer`) Limit diagnostics to the given namespace. + • {lnum}? (`integer`) Limit diagnostics to the given line number. + • {severity}? (`vim.diagnostic.SeverityFilter`) See + |diagnostic-severity|. + +*vim.diagnostic.GotoOpts* + Extends: |vim.diagnostic.GetOpts| + + Configuration table with the following keys: + + Fields: ~ + • {cursor_position}? (`{[1]:integer,[2]:integer}`, default: current cursor position) + Cursor position as a `(row, col)` tuple. See + |nvim_win_get_cursor()|. + • {wrap}? (`boolean`, default: `true`) Whether to loop + around file or not. Similar to 'wrapscan'. + • {severity} (`vim.diagnostic.Severity`) See + |diagnostic-severity|. + • {float}? (`boolean|vim.diagnostic.Opts.Float`, default: + `true`) If `true`, call + |vim.diagnostic.open_float()| after moving. If a + table, pass the table as the {opts} parameter to + |vim.diagnostic.open_float()|. Unless overridden, + the float will show diagnostics at the new cursor + position (as if "cursor" were passed to the + "scope" option). + • {win_id}? (`integer`, default: `0`) Window ID + *vim.diagnostic.NS* Fields: ~ • {name} (`string`) - • {opts} (`vim.diagnostic.Opts`) + • {opts} (`vim.diagnostic.Opts`) See |vim.diagnostic.Opts|. • {user_data} (`table`) • {disabled}? (`boolean`) *vim.diagnostic.Opts* + Each of the configuration options below accepts one of the following: + • `false`: Disable this feature + • `true`: Enable this feature, use default settings. + • `table`: Enable this feature with overrides. Use an empty table to use + default values. + • `function`: Function with signature (namespace, bufnr) that returns any + of the above. Fields: ~ - • {float}? (`boolean|vim.diagnostic.Opts.Float`) - • {update_in_insert}? (`boolean`) - • {underline}? (`boolean|vim.diagnostic.Opts.Underline`) - • {virtual_text}? (`boolean|vim.diagnostic.Opts.VirtualText`) - • {signs}? (`boolean|vim.diagnostic.Opts.Signs`) - • {severity_sort}? (`boolean|{reverse?:boolean}`) + • {underline}? (`boolean|vim.diagnostic.Opts.Underline|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Underline`, default: `true`) + Use underline for diagnostics. + • {virtual_text}? (`boolean|vim.diagnostic.Opts.VirtualText|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualText`, 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. + • {signs}? (`boolean|vim.diagnostic.Opts.Signs|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Signs`, default: `true`) + Use signs for diagnostics |diagnostic-signs|. + • {float}? (`boolean|vim.diagnostic.Opts.Float|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Float`) + Options for floating windows. See + |vim.diagnostic.Opts.Float|. + • {update_in_insert}? (`boolean`, default: `false) Update diagnostics + in Insert mode (if `false`, diagnostics are + updated on |InsertLeave|) + • {severity_sort}? (`boolean|{reverse?:boolean}`, 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 *vim.diagnostic.Opts.Float* Fields: ~ - • {bufnr}? (`integer`) - • {namespace}? (`integer`) - • {scope}? (`'line'|'buffer'|'cursor'|'c'|'l'|'b'`) - • {pos}? (`integer|{[1]:integer,[2]:integer}`) - • {severity_sort}? (`boolean|{reverse?:boolean}`) - • {severity}? (`vim.diagnostic.SeverityFilter`) - • {header}? (`string|{[1]:string,[2]:any}`) - • {source}? (`boolean|string`) - • {format}? (`fun(diagnostic:vim.Diagnostic): string`) - • {prefix}? (`string|table`) - • {suffix}? (`string|table`) + • {bufnr}? (`integer`, default: current buffer) Buffer number + to show diagnostics from. + • {namespace}? (`integer`) Limit diagnostics to the given namespace + • {scope}? (`'line'|'buffer'|'cursor'|'c'|'l'|'b'`, default: + `line`) Show diagnostics from the whole buffer + (`buffer"`, the current cursor line (`line`), or the + current cursor position (`cursor`). Shorthand + versions are also accepted (`c` for `cursor`, `l` + for `line`, `b` for `buffer`). + • {pos}? (`integer|{[1]:integer,[2]:integer}`) If {scope} is + "line" or "cursor", use this position rather than + the cursor position. If a number, interpreted as a + line number; otherwise, a (row, col) tuple. + • {severity_sort}? (`boolean|{reverse?:boolean}`, default: `false`) + Sort diagnostics by severity. Overrides the setting + from |vim.diagnostic.config()|. + • {severity}? (`vim.diagnostic.SeverityFilter`) See + |diagnostic-severity|. Overrides the setting from + |vim.diagnostic.config()|. + • {header}? (`string|{[1]:string,[2]:any}`) String to use as the + header for the floating window. If a table, it is + interpreted as a `[text, hl_group]` tuple. Overrides + the setting from |vim.diagnostic.config()|. + • {source}? (`boolean|'if_many'`) Include the diagnostic source + in the message. Use "if_many" to only show sources + if there is more than one source of diagnostics in + the buffer. Otherwise, any truthy value means to + always show the diagnostic source. Overrides the + setting from |vim.diagnostic.config()|. + • {format}? (`fun(diagnostic:vim.Diagnostic): string`) A + function that takes a diagnostic as input and + returns a string. The return value is the text used + to display the diagnostic. Overrides the setting + from |vim.diagnostic.config()|. + • {prefix}? (`string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)`) + Prefix each diagnostic in the floating window: + • If a `function`, {i} is the index of the + diagnostic being evaluated and {total} is the + total number of diagnostics displayed in the + window. The function should return a `string` + which is prepended to each diagnostic in the + window as well as an (optional) highlight group + which will be used to highlight the prefix. + • If a `table`, it is interpreted as a `[text, + hl_group]` tuple as in |nvim_echo()| + • If a `string`, it is prepended to each diagnostic + in the window with no highlight. Overrides the + setting from |vim.diagnostic.config()|. + • {suffix}? (`string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)`) + Same as {prefix}, but appends the text to the + diagnostic instead of prepending it. Overrides the + setting from |vim.diagnostic.config()|. • {focus_id}? (`string`) *vim.diagnostic.Opts.Signs* Fields: ~ - • {severity}? (`vim.diagnostic.SeverityFilter`) - • {priority}? (`integer`) - • {text}? (`table`) - • {numhl}? (`table`) - • {linehl}? (`table`) - • {texthl}? (`table`) + • {severity}? (`vim.diagnostic.SeverityFilter`) Only show virtual text + for diagnostics matching the given severity + |diagnostic-severity| + • {priority}? (`integer`, 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. *vim.diagnostic.Opts.Underline* Fields: ~ - • {severity}? (`vim.diagnostic.SeverityFilter`) + • {severity}? (`vim.diagnostic.SeverityFilter`) Only underline + diagnostics matching the given severity + |diagnostic-severity|. *vim.diagnostic.Opts.VirtualText* Fields: ~ - • {severity}? (`vim.diagnostic.SeverityFilter`) - • {source}? (`boolean|string`) - • {prefix}? (`string|function`) - • {suffix}? (`string|function`) - • {spacing}? (`integer`) - • {format}? (`function`) - • {hl_mode}? (`'replace'|'combine'|'blend'`) - • {virt_text}? (`{[1]:string,[2]:any}[]`) - • {virt_text_pos}? (`'eol'|'overlay'|'right_align'|'inline'`) - • {virt_text_win_col}? (`integer`) - • {virt_text_hide}? (`boolean`) - -*vim.diagnostic.OptsResolved* - - Fields: ~ - • {float} (`vim.diagnostic.Opts.Float`) - • {update_in_insert} (`boolean`) - • {underline} (`vim.diagnostic.Opts.Underline`) - • {virtual_text} (`vim.diagnostic.Opts.VirtualText`) - • {signs} (`vim.diagnostic.Opts.Signs`) - • {severity_sort} (`{reverse?:boolean}`) + • {severity}? (`vim.diagnostic.SeverityFilter`) Only show + virtual text for diagnostics matching the given + severity |diagnostic-severity| + • {source}? (`boolean|"if_many"`) 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}? (`integer`) Amount of empty spaces inserted at + the beginning of the virtual text. + • {prefix}? (`string|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string)`) + Prepend diagnostic message with prefix. If a + `function`, {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|(fun(diagnostic:vim.Diagnostic): + string)`) Append diagnostic message with suffix. + This can be used to render an LSP diagnostic + error code. + • {format}? (`fun(diagnostic:vim.Diagnostic): 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 +< + • {hl_mode}? (`'replace'|'combine'|'blend'`) See + |nvim_buf_set_extmark()|. + • {virt_text}? (`{[1]:string,[2]:any}[]`) See + |nvim_buf_set_extmark()|. + • {virt_text_pos}? (`'eol'|'overlay'|'right_align'|'inline'`) See + |nvim_buf_set_extmark()|. + • {virt_text_win_col}? (`integer`) See |nvim_buf_set_extmark()|. + • {virt_text_hide}? (`boolean`) See |nvim_buf_set_extmark()|. config({opts}, {namespace}) *vim.diagnostic.config()* @@ -461,101 +593,16 @@ config({opts}, {namespace}) *vim.diagnostic.config()* then virtual text will not be enabled for those diagnostics. - Note: ~ - • Each of the configuration options below accepts one of the following: - • `false`: Disable this feature - • `true`: Enable this feature, use default settings. - • `table`: Enable this feature with overrides. Use an empty table to - use default values. - • `function`: Function with signature (namespace, bufnr) that returns - any of the above. - Parameters: ~ - • {opts} (`table?`) When omitted or "nil", retrieve the current - 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| - • 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: >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: >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 + • {opts} (`vim.diagnostic.Opts?`) When omitted or `nil`, retrieve + the current configuration. Otherwise, a configuration + table (see |vim.diagnostic.Opts|). • {namespace} (`integer?`) Update the options for the given namespace. When omitted, update the global diagnostic options. Return: ~ - (`table?`) table of current diagnostic config if `opts` is omitted. + (`vim.diagnostic.Opts?`) Current diagnostic config if {opts} is + omitted. See |vim.diagnostic.Opts|. count({bufnr}, {opts}) *vim.diagnostic.count()* Get current diagnostics count. @@ -563,14 +610,10 @@ count({bufnr}, {opts}) *vim.diagnostic.count()* Parameters: ~ • {bufnr} (`integer?`) Buffer number to get diagnostics from. Use 0 for current buffer or nil for all buffers. - • {opts} (`table?`) A table with the following keys: - • namespace: (number) Limit diagnostics to the given - namespace. - • lnum: (number) Limit diagnostics to the given line number. - • severity: See |diagnostic-severity|. + • {opts} (`vim.diagnostic.GetOpts?`) See |vim.diagnostic.GetOpts|. Return: ~ - (`table`) A table with actually present severity values as keys (see + (`table`) Table with actually present severity values as keys (see |diagnostic-severity|) and integer counts as values. disable({bufnr}, {namespace}) *vim.diagnostic.disable()* @@ -599,8 +642,7 @@ fromqflist({list}) *vim.diagnostic.fromqflist()* |getloclist()|. Return: ~ - (`vim.Diagnostic[]`) array of |diagnostic-structure|. See - |vim.Diagnostic|. + (`vim.Diagnostic[]`) See |vim.Diagnostic|. get({bufnr}, {opts}) *vim.diagnostic.get()* Get current diagnostics. @@ -611,15 +653,10 @@ get({bufnr}, {opts}) *vim.diagnostic.get()* Parameters: ~ • {bufnr} (`integer?`) Buffer number to get diagnostics from. Use 0 for current buffer or nil for all buffers. - • {opts} (`table?`) A table with the following keys: - • namespace: (number) Limit diagnostics to the given - namespace. - • lnum: (number) Limit diagnostics to the given line number. - • severity: See |diagnostic-severity|. + • {opts} (`vim.diagnostic.GetOpts?`) See |vim.diagnostic.GetOpts|. Return: ~ - (`vim.Diagnostic[]`) table A list of diagnostic items - |diagnostic-structure|. Keys `bufnr`, `end_lnum`, `end_col`, and + (`vim.Diagnostic[]`) Fields `bufnr`, `end_lnum`, `end_col`, and `severity` are guaranteed to be present. See |vim.Diagnostic|. get_namespace({namespace}) *vim.diagnostic.get_namespace()* @@ -629,20 +666,20 @@ get_namespace({namespace}) *vim.diagnostic.get_namespace()* • {namespace} (`integer`) Diagnostic namespace Return: ~ - (`table`) Namespace metadata + (`vim.diagnostic.NS`) Namespace metadata. See |vim.diagnostic.NS|. get_namespaces() *vim.diagnostic.get_namespaces()* Get current diagnostic namespaces. Return: ~ - (`table`) A list of active diagnostic + (`table`) List of active diagnostic namespaces |vim.diagnostic|. get_next({opts}) *vim.diagnostic.get_next()* Get the next diagnostic closest to the cursor position. Parameters: ~ - • {opts} (`table?`) See |vim.diagnostic.goto_next()| + • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|. Return: ~ (`vim.Diagnostic?`) Next diagnostic. See |vim.Diagnostic|. @@ -651,17 +688,17 @@ get_next_pos({opts}) *vim.diagnostic.get_next_pos()* Return the position of the next diagnostic in the current buffer. Parameters: ~ - • {opts} (`table?`) See |vim.diagnostic.goto_next()| + • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|. Return: ~ - (`table|false`) Next diagnostic position as a (row, col) tuple or + (`table|false`) Next diagnostic position as a `(row, col)` tuple or false if no next diagnostic. get_prev({opts}) *vim.diagnostic.get_prev()* Get the previous diagnostic closest to the cursor position. Parameters: ~ - • {opts} (`table?`) See |vim.diagnostic.goto_next()| + • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|. Return: ~ (`vim.Diagnostic?`) Previous diagnostic. See |vim.Diagnostic|. @@ -670,39 +707,23 @@ get_prev_pos({opts}) *vim.diagnostic.get_prev_pos()* Return the position of the previous diagnostic in the current buffer. Parameters: ~ - • {opts} (`table?`) See |vim.diagnostic.goto_next()| + • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|. Return: ~ - (`table|false`) Previous diagnostic position as a (row, col) tuple or - false if there is no prior diagnostic + (`table|false`) Previous diagnostic position as a `(row, col)` tuple + or `false` if there is no prior diagnostic. goto_next({opts}) *vim.diagnostic.goto_next()* Move to the next diagnostic. Parameters: ~ - • {opts} (`table?`) Configuration table with the following keys: - • {namespace} (`integer`) Only consider diagnostics from the - given namespace. - • {cursor_position}? (`{[1]:integer,[2]:integer}`) Cursor - position as a (row, col) tuple. See |nvim_win_get_cursor()|. - Defaults to the current cursor position. - • {wrap}? (`boolean`, default: `true`) Whether to loop around - file or not. Similar to 'wrapscan'. - • {severity} (`vim.diagnostic.Severity`) See - |diagnostic-severity|. - • {float}? (`boolean|vim.diagnostic.Opts.Float`, default: - `true`) If "true", call |vim.diagnostic.open_float()| after - moving. If a table, pass the table as the {opts} parameter - to |vim.diagnostic.open_float()|. Unless overridden, the - float will show diagnostics at the new cursor position (as - if "cursor" were passed to the "scope" option). - • {win_id}? (`integer`, default: `0`) Window ID + • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|. goto_prev({opts}) *vim.diagnostic.goto_prev()* Move to the previous diagnostic in the current buffer. Parameters: ~ - • {opts} (`table?`) See |vim.diagnostic.goto_next()| + • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|. hide({namespace}, {bufnr}) *vim.diagnostic.hide()* Hide currently displayed diagnostics. @@ -740,7 +761,7 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults}) WARNING filename:27:3: Variable 'foo' does not exist < - This can be parsed into a diagnostic |diagnostic-structure| with: >lua + This can be parsed into |vim.Diagnostic| structure with: >lua local s = "WARNING filename:27:3: Variable 'foo' does not exist" local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$" local groups = { "severity", "lnum", "col", "message" } @@ -750,9 +771,8 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults}) Parameters: ~ • {str} (`string`) String to parse diagnostics from. • {pat} (`string`) Lua pattern with capture groups. - • {groups} (`string[]`) List of fields in a - |diagnostic-structure| to associate with captures from - {pat}. + • {groups} (`string[]`) List of fields in a |vim.Diagnostic| + structure to associate with captures from {pat}. • {severity_map} (`table`) A table mapping the severity field from {groups} with an item from |vim.diagnostic.severity|. • {defaults} (`table?`) Table of default values for any fields not @@ -760,61 +780,15 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults}) default to 0 and "severity" defaults to ERROR. Return: ~ - (`vim.Diagnostic?`) |diagnostic-structure| or `nil` if {pat} fails to - match {str}. See |vim.Diagnostic|. + (`vim.Diagnostic?`) |vim.Diagnostic| structure or `nil` if {pat} fails + to match {str}. open_float({opts}) *vim.diagnostic.open_float()* Show diagnostics in a floating window. Parameters: ~ - • {opts} (`table?`) Configuration table with the same keys as - |vim.lsp.util.open_floating_preview()| in addition to the - following: - • bufnr: (number) Buffer number to show diagnostics from. - Defaults to the current buffer. - • namespace: (number) Limit diagnostics to the given namespace - • scope: (string, default "line") Show diagnostics from the - whole buffer ("buffer"), the current cursor line ("line"), - or the current cursor position ("cursor"). Shorthand - versions are also accepted ("c" for "cursor", "l" for - "line", "b" for "buffer"). - • pos: (number or table) If {scope} is "line" or "cursor", use - this position rather than the cursor position. If a number, - interpreted as a line number; otherwise, a (row, col) tuple. - • severity_sort: (default false) Sort diagnostics by severity. - Overrides the setting from |vim.diagnostic.config()|. - • severity: See |diagnostic-severity|. Overrides the setting - from |vim.diagnostic.config()|. - • header: (string or table) String to use as the header for - the floating window. If a table, it is interpreted as a - [text, hl_group] tuple. Overrides the setting from - |vim.diagnostic.config()|. - • source: (boolean or string) Include the diagnostic source in - the message. Use "if_many" to only show sources if there is - more than one source of diagnostics in the buffer. - Otherwise, any truthy value means to always show the - diagnostic source. Overrides the setting from - |vim.diagnostic.config()|. - • 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. Overrides the setting from - |vim.diagnostic.config()|. - • prefix: (function, string, or table) Prefix each diagnostic - in the floating window. If a function, it must have the - signature (diagnostic, i, total) -> (string, string), where - {i} is the index of the diagnostic being evaluated and - {total} is the total number of diagnostics displayed in the - window. The function should return a string which is - prepended to each diagnostic in the window as well as an - (optional) highlight group which will be used to highlight - the prefix. If {prefix} is a table, it is interpreted as a - [text, hl_group] tuple as in |nvim_echo()|; otherwise, if - {prefix} is a string, it is prepended to each diagnostic in - the window with no highlight. 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()|. + • {opts} (`vim.diagnostic.Opts.Float?`) See + |vim.diagnostic.Opts.Float|. Return (multiple): ~ (`integer?`) float_bufnr @@ -840,10 +814,9 @@ set({namespace}, {bufnr}, {diagnostics}, {opts}) *vim.diagnostic.set()* Parameters: ~ • {namespace} (`integer`) The diagnostic namespace • {bufnr} (`integer`) Buffer number - • {diagnostics} (`vim.Diagnostic[]`) A list of diagnostic items - |diagnostic-structure|. See |vim.Diagnostic|. - • {opts} (`table?`) Display options to pass to - |vim.diagnostic.show()| + • {diagnostics} (`vim.Diagnostic[]`) See |vim.Diagnostic|. + • {opts} (`vim.diagnostic.Opts?`) Display options to pass to + |vim.diagnostic.show()|. See |vim.diagnostic.Opts|. setloclist({opts}) *vim.diagnostic.setloclist()* Add buffer diagnostics to the location list. @@ -890,19 +863,18 @@ show({namespace}, {bufnr}, {diagnostics}, {opts}) list of diagnostics without saving them or to display only a subset of diagnostics. May not be used when {namespace} or {bufnr} is nil. See |vim.Diagnostic|. - • {opts} (`table?`) Display options. See - |vim.diagnostic.config()|. + • {opts} (`vim.diagnostic.Opts?`) Display options. See + |vim.diagnostic.Opts|. toqflist({diagnostics}) *vim.diagnostic.toqflist()* Convert a list of diagnostics to a list of quickfix items that can be passed to |setqflist()| or |setloclist()|. Parameters: ~ - • {diagnostics} (`vim.Diagnostic[]`) List of diagnostics - |diagnostic-structure|. See |vim.Diagnostic|. + • {diagnostics} (`vim.Diagnostic[]`) See |vim.Diagnostic|. Return: ~ - (`table[]`) of quickfix list items |setqflist-what| + (`table[]`) Quickfix list items |setqflist-what| vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index 511fb590cc..31b1c412c7 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -673,17 +673,18 @@ buf_request_sync({bufnr}, {method}, {params}, {timeout_ms}) Calls |vim.lsp.buf_request_all()| but blocks Nvim while awaiting the result. Parameters are the same as |vim.lsp.buf_request_all()| but the - result is different. Waits a maximum of {timeout_ms} (default 1000) ms. + result is different. Waits a maximum of {timeout_ms}. Parameters: ~ • {bufnr} (`integer`) Buffer handle, or 0 for current. • {method} (`string`) LSP method name • {params} (`table?`) Parameters to send to the server - • {timeout_ms} (`integer?`) Maximum time in milliseconds to wait for a - result. Defaults to 1000 + • {timeout_ms} (`integer?`, default: `1000`) Maximum time in + milliseconds to wait for a result. Return (multiple): ~ - (`table`) result Map of client_id:request_result. + (`table?`) result Map + of client_id:request_result. (`string?`) err On timeout, cancel, or error, `err` is a string describing the failure reason, and `result` is nil. @@ -946,13 +947,15 @@ Lua module: vim.lsp.client *lsp-client* server. • {config} (`vim.lsp.ClientConfig`) copy of the table that was passed by the user to - |vim.lsp.start_client()|. + |vim.lsp.start_client()|. See + |vim.lsp.ClientConfig|. • {server_capabilities} (`lsp.ServerCapabilities?`) Response from the server sent on initialize` describing the server's capabilities. • {progress} (`vim.lsp.Client.Progress`) A ring buffer (|vim.ringbuf()|) containing progress messages - sent by the server. + sent by the server. See + |vim.lsp.Client.Progress|. • {initialized} (`true?`) • {workspace_folders} (`lsp.WorkspaceFolder[]?`) The workspace folders configured in the client when the @@ -968,9 +971,28 @@ Lua module: vim.lsp.client *lsp-client* action, code lenses, ...) triggers the command. Client commands take precedence over the global command registry. - • {settings} (`table`) - • {flags} (`table`) - • {get_language_id} (`fun(bufnr: integer, filetype: string): string`) + • {settings} (`table`) Map with language server specific + settings. These are returned to the language + server if requested via + `workspace/configuration`. Keys are + case-sensitive. + • {flags} (`table`) A table with flags for the client. + The current (experimental) flags are: + • {allow_incremental_sync}? (`boolean`) Allow + using incremental sync for buffer edits + (defailt: `true`) + • {debounce_text_changes} (`integer`, default: + `150`) Debounce `didChange` notifications to + the server by the given number in + milliseconds. No debounce occurs if `nil`. + • {exit_timeout} (`integer|false`, 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. + • {get_language_id} (`fun(bufnr: integer, filetype: string): + string`) • {capabilities} (`lsp.ClientCapabilities`) The capabilities provided by the client (editor or tool) • {dynamic_capabilities} (`lsp.DynamicCapabilities`) @@ -1021,6 +1043,7 @@ Lua module: vim.lsp.client *lsp-client* *vim.lsp.Client.Progress* Extends: |vim.Ringbuf| + Fields: ~ • {pending} (`table`) @@ -1070,10 +1093,8 @@ Lua module: vim.lsp.client *lsp-client* • {handlers}? (`table`) Map of language server method names to |lsp-handler| • {settings}? (`table`) Map with language server specific - settings. These are returned to the language - server if requested via - `workspace/configuration`. Keys are - case-sensitive. + settings. See the {settings} in + |vim.lsp.Client|. • {commands}? (`table`) Table that maps string of clientside commands to user-defined functions. Commands @@ -1101,13 +1122,14 @@ Lua module: vim.lsp.client *lsp-client* possible errors. Use `vim.lsp.rpc.client_errors[code]` to get human-friendly name. - • {before_init}? (`vim.lsp.client.before_init_cb`) Callback - invoked before the LSP "initialize" phase, where - `params` contains the parameters being sent to - the server and `config` is the config that was - passed to |vim.lsp.start_client()|. You can use - this to modify parameters before they are sent. - • {on_init}? (`elem_or_list`) + • {before_init}? (`fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig)`) + Callback invoked before the LSP "initialize" + phase, where `params` contains the parameters + being sent to the server and `config` is the + config that was passed to + |vim.lsp.start_client()|. You can use this to + modify parameters before they are sent. + • {on_init}? (`elem_or_list`) Callback invoked after LSP "initialize", where `result` is a table of `capabilities` and anything else the server may send. For example, @@ -1115,13 +1137,13 @@ Lua module: vim.lsp.client *lsp-client* if `capabilities.offsetEncoding` was sent to it. You can only modify the `client.offset_encoding` here before any notifications are sent. - • {on_exit}? (`elem_or_list`) + • {on_exit}? (`elem_or_list`) Callback invoked on client exit. • code: exit code of the process • signal: number describing the signal used to terminate (if any) • client_id: client handle - • {on_attach}? (`elem_or_list`) + • {on_attach}? (`elem_or_list`) Callback invoked when client attaches to a buffer. • {trace}? (`'off'|'messages'|'verbose'`, default: "off") @@ -1129,18 +1151,19 @@ Lua module: vim.lsp.client *lsp-client* initialize request. Invalid/empty values will • {flags}? (`table`) 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}? (`boolean`) Allow + using incremental sync for buffer edits + (defailt: `true`) + • {debounce_text_changes} (`integer`, default: + `150`) Debounce `didChange` notifications to + the server by the given number in + milliseconds. No debounce occurs if `nil`. + • {exit_timeout} (`integer|false`, 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 on initialization. @@ -1176,6 +1199,7 @@ Lua module: vim.lsp.buf *lsp-buf* *vim.lsp.LocationOpts* Extends: |vim.lsp.ListOpts| + Fields: ~ • {reuse_win}? (`boolean`) Jump to existing window if buffer is already open. @@ -1443,7 +1467,7 @@ on_diagnostic({_}, {result}, {ctx}, {config}) Parameters: ~ • {result} (`lsp.DocumentDiagnosticReport`) • {ctx} (`lsp.HandlerContext`) - • {config} (`table`) Configuration table (see + • {config} (`vim.diagnostic.Opts`) Configuration table (see |vim.diagnostic.config()|). *vim.lsp.diagnostic.on_publish_diagnostics()* diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index c785106ca8..42577cae2e 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -1831,15 +1831,15 @@ vim.inspect_pos({bufnr}, {row}, {col}, {filter}) *vim.inspect_pos()* • {col} (`integer?`) col to inspect, 0-based. Defaults to the col of the current cursor • {filter} (`table?`) 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) + • {syntax} (`boolean`, default: `true`) Include syntax based + highlight groups. + • {treesitter} (`boolean`, default: `true`) Include + treesitter based highlight groups. • {extmarks} (`boolean|"all"`, default: true) Include extmarks. When `all`, then extmarks without a `hl_group` will also be included. - • {semantic_tokens} (`boolean`) Include semantic token - highlights (defaults to true) + • {semantic_tokens} (`boolean`, default: true) Include + semantic token highlights. Return: ~ (`table`) a table with the following key-value pairs. Items are in @@ -1863,7 +1863,16 @@ vim.show_pos({bufnr}, {row}, {col}, {filter}) *vim.show_pos()* the current cursor • {col} (`integer?`) col to inspect, 0-based. Defaults to the col of the current cursor - • {filter} (`table?`) see |vim.inspect_pos()| + • {filter} (`table?`) A table with the following fields: + • {syntax} (`boolean`, default: `true`) Include syntax based + highlight groups. + • {treesitter} (`boolean`, default: `true`) Include + treesitter based highlight groups. + • {extmarks} (`boolean|"all"`, default: true) Include + extmarks. When `all`, then extmarks without a `hl_group` + will also be included. + • {semantic_tokens} (`boolean`, default: true) Include + semantic token highlights. @@ -1989,7 +1998,7 @@ vim.gsplit({s}, {sep}, {opts}) *vim.gsplit()* end of the sequence. Return: ~ - (`function`) Iterator over the split components + (`fun():string?`) Iterator over the split components See also: ~ • |string.gmatch()| @@ -2089,7 +2098,7 @@ vim.ringbuf({size}) *vim.ringbuf()* • {size} (`integer`) Return: ~ - (`table`) + (`vim.Ringbuf`) ringbuf See |vim.Ringbuf|. vim.spairs({t}) *vim.spairs()* Enumerates key-value pairs of a table, ordered by key. @@ -2097,8 +2106,10 @@ vim.spairs({t}) *vim.spairs()* Parameters: ~ • {t} (`table`) Dict-like table - Return: ~ - (`function`) |for-in| iterator over sorted keys and their values + Return (multiple): ~ + (`fun(table: table, index?: K):K, V`) |for-in| iterator over + sorted keys and their values + (`table`) See also: ~ • Based on @@ -2334,8 +2345,8 @@ vim.tbl_map({func}, {t}) *vim.tbl_map()* Apply a function to all values of a table. Parameters: ~ - • {func} (`function`) Function - • {t} (`table`) Table + • {func} (`fun(value: T): any`) Function + • {t} (`table`) Table Return: ~ (`table`) Table of transformed values diff --git a/runtime/lua/vim/_inspector.lua b/runtime/lua/vim/_inspector.lua index a19d40c50d..2999630fce 100644 --- a/runtime/lua/vim/_inspector.lua +++ b/runtime/lua/vim/_inspector.lua @@ -1,17 +1,20 @@ --- @class vim._inspector.Filter --- @inlinedoc --- ---- Include syntax based highlight groups (defaults to true) +--- Include syntax based highlight groups. +--- (default: `true`) --- @field syntax boolean --- ---- Include treesitter based highlight groups (defaults to true) +--- Include treesitter based highlight groups. +--- (default: `true`) --- @field treesitter boolean --- --- Include extmarks. When `all`, then extmarks without a `hl_group` will also be included. --- (default: true) --- @field extmarks boolean|"all" --- ---- Include semantic token highlights (defaults to true) +--- Include semantic token highlights. +--- (default: true) --- @field semantic_tokens boolean local defaults = { syntax = true, @@ -145,7 +148,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? vim._inspector.Filter (table) see |vim.inspect_pos()| +---@param filter? vim._inspector.Filter function vim.show_pos(bufnr, row, col, filter) local items = vim.inspect_pos(bufnr, row, col, filter) diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua index 3979e5512c..9483474a40 100644 --- a/runtime/lua/vim/diagnostic.lua +++ b/runtime/lua/vim/diagnostic.lua @@ -42,15 +42,44 @@ local M = {} --- --- @field namespace? integer +--- Each of the configuration options below accepts one of the following: +--- - `false`: Disable this feature +--- - `true`: Enable this feature, use default settings. +--- - `table`: Enable this feature with overrides. Use an empty table to use default values. +--- - `function`: Function with signature (namespace, bufnr) that returns any of the above. --- @class vim.diagnostic.Opts ---- @field float? boolean|vim.diagnostic.Opts.Float +--- +--- Use underline for diagnostics. +--- (default: `true`) +--- @field underline? boolean|vim.diagnostic.Opts.Underline|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Underline +--- +--- Use virtual text for diagnostics. If multiple diagnostics are set for a +--- namespace, one prefix per diagnostic + the last diagnostic message are +--- shown. +--- (default: `true`) +--- @field virtual_text? boolean|vim.diagnostic.Opts.VirtualText|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualText +--- +--- Use signs for diagnostics |diagnostic-signs|. +--- (default: `true`) +--- @field signs? boolean|vim.diagnostic.Opts.Signs|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Signs +--- +--- Options for floating windows. See |vim.diagnostic.Opts.Float|. +--- @field float? boolean|vim.diagnostic.Opts.Float|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Float +--- +--- Update diagnostics in Insert mode +--- (if `false`, diagnostics are updated on |InsertLeave|) +--- (default: `false) --- @field update_in_insert? boolean ---- @field underline? boolean|vim.diagnostic.Opts.Underline ---- @field virtual_text? boolean|vim.diagnostic.Opts.VirtualText ---- @field signs? boolean|vim.diagnostic.Opts.Signs +--- +--- 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 +--- (default: `false) --- @field severity_sort? boolean|{reverse?:boolean} ---- @class vim.diagnostic.OptsResolved +--- @class (private) vim.diagnostic.OptsResolved --- @field float vim.diagnostic.Opts.Float --- @field update_in_insert boolean --- @field underline vim.diagnostic.Opts.Underline @@ -59,42 +88,156 @@ local M = {} --- @field severity_sort {reverse?:boolean} --- @class vim.diagnostic.Opts.Float +--- +--- Buffer number to show diagnostics from. +--- (default: current buffer) --- @field bufnr? integer +--- +--- Limit diagnostics to the given namespace --- @field namespace? integer +--- +--- Show diagnostics from the whole buffer (`buffer"`, the current cursor line +--- (`line`), or the current cursor position (`cursor`). Shorthand versions +--- are also accepted (`c` for `cursor`, `l` for `line`, `b` for `buffer`). +--- (default: `line`) --- @field scope? 'line'|'buffer'|'cursor'|'c'|'l'|'b' +--- +--- If {scope} is "line" or "cursor", use this position rather than the cursor +--- position. If a number, interpreted as a line number; otherwise, a +--- (row, col) tuple. --- @field pos? integer|{[1]:integer,[2]:integer} +--- +--- Sort diagnostics by severity. +--- Overrides the setting from |vim.diagnostic.config()|. +--- (default: `false`) --- @field severity_sort? boolean|{reverse?:boolean} +--- +--- See |diagnostic-severity|. +--- Overrides the setting from |vim.diagnostic.config()|. --- @field severity? vim.diagnostic.SeverityFilter +--- +--- String to use as the header for the floating window. If a table, it is +--- interpreted as a `[text, hl_group]` tuple. +--- Overrides the setting from |vim.diagnostic.config()|. --- @field header? string|{[1]:string,[2]:any} ---- @field source? boolean|string +--- +--- Include the diagnostic source in the message. +--- Use "if_many" to only show sources if there is more than one source of +--- diagnostics in the buffer. Otherwise, any truthy value means to always show +--- the diagnostic source. +--- Overrides the setting from |vim.diagnostic.config()|. +--- @field source? boolean|'if_many' +--- +--- A function that takes a diagnostic as input and returns a string. +--- The return value is the text used to display the diagnostic. +--- Overrides the setting from |vim.diagnostic.config()|. --- @field format? fun(diagnostic:vim.Diagnostic): string +--- +--- Prefix each diagnostic in the floating window: +--- - If a `function`, {i} is the index of the diagnostic being evaluated and +--- {total} is the total number of diagnostics displayed in the window. The +--- function should return a `string` which is prepended to each diagnostic +--- in the window as well as an (optional) highlight group which will be +--- used to highlight the prefix. +--- - If a `table`, it is interpreted as a `[text, hl_group]` tuple as +--- in |nvim_echo()| +--- - If a `string`, it is prepended to each diagnostic in the window with no +--- highlight. +--- Overrides the setting from |vim.diagnostic.config()|. --- @field prefix? string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string) +--- +--- Same as {prefix}, but appends the text to the diagnostic instead of +--- prepending it. +--- Overrides the setting from |vim.diagnostic.config()|. --- @field suffix? string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string) +--- --- @field focus_id? string --- @class vim.diagnostic.Opts.Underline +--- +--- Only underline diagnostics matching the given +--- severity |diagnostic-severity|. --- @field severity? vim.diagnostic.SeverityFilter --- @class vim.diagnostic.Opts.VirtualText +--- +--- Only show virtual text for diagnostics matching the given +--- severity |diagnostic-severity| --- @field severity? vim.diagnostic.SeverityFilter ---- @field source? boolean|string ---- @field prefix? string|function ---- @field suffix? string|function +--- +--- 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. +--- @field source? boolean|"if_many" +--- +--- Amount of empty spaces inserted at the beginning of the virtual text. --- @field spacing? integer ---- @field format? function +--- +--- Prepend diagnostic message with prefix. If a `function`, {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. +--- @field prefix? string|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string) +--- +--- Append diagnostic message with suffix. +--- This can be used to render an LSP diagnostic error code. +--- @field suffix? string|(fun(diagnostic:vim.Diagnostic): 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 +--- ``` +--- @field format? fun(diagnostic:vim.Diagnostic): string +--- +--- See |nvim_buf_set_extmark()|. --- @field hl_mode? 'replace'|'combine'|'blend' +--- +--- See |nvim_buf_set_extmark()|. --- @field virt_text? {[1]:string,[2]:any}[] +--- +--- See |nvim_buf_set_extmark()|. --- @field virt_text_pos? 'eol'|'overlay'|'right_align'|'inline' +--- +--- See |nvim_buf_set_extmark()|. --- @field virt_text_win_col? integer +--- +--- See |nvim_buf_set_extmark()|. --- @field virt_text_hide? boolean --- @class vim.diagnostic.Opts.Signs +--- +--- Only show virtual text for diagnostics matching the given +--- severity |diagnostic-severity| --- @field severity? vim.diagnostic.SeverityFilter +--- +--- 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. +--- (default: `10`) --- @field priority? integer +--- +--- 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', ... } } +--- }) +--- ``` --- @field text? table +--- +--- A table mapping |diagnostic-severity| to the highlight group used for the +--- line number where the sign is placed. --- @field numhl? table +--- +--- A table mapping |diagnostic-severity| to the highlight group used for the +--- whole line the sign is placed in. --- @field linehl? table ---- @field texthl? table --- @nodoc --- @enum vim.diagnostic.Severity @@ -752,83 +895,11 @@ end --- --- then virtual text will not be enabled for those diagnostics. --- ----@note Each of the configuration options below accepts one of the following: ---- - `false`: Disable this feature ---- - `true`: Enable this feature, use default settings. ---- - `table`: Enable this feature with overrides. Use an empty table to use default values. ---- - `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: ---- - underline: (default true) Use underline for diagnostics. Options: ---- * 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: ---- ```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: ---- ```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 ---- ----@param namespace integer? Update the options for the given namespace. When omitted, update the ---- global diagnostic options. ---- ----@return vim.diagnostic.Opts? (table?) table of current diagnostic config if `opts` is omitted. +---@param opts vim.diagnostic.Opts? When omitted or `nil`, retrieve the current +--- configuration. Otherwise, a configuration table (see |vim.diagnostic.Opts|). +---@param namespace integer? Update the options for the given namespace. +--- When omitted, update the global diagnostic options. +---@return vim.diagnostic.Opts? : Current diagnostic config if {opts} is omitted. function M.config(opts, namespace) vim.validate({ opts = { opts, 't', true }, @@ -873,8 +944,8 @@ end --- ---@param namespace integer The diagnostic namespace ---@param bufnr integer Buffer number ----@param diagnostics vim.Diagnostic[] A list of diagnostic items |diagnostic-structure| ----@param opts? vim.diagnostic.Opts (table) Display options to pass to |vim.diagnostic.show()| +---@param diagnostics vim.Diagnostic[] +---@param opts? vim.diagnostic.Opts Display options to pass to |vim.diagnostic.show()| function M.set(namespace, bufnr, diagnostics, opts) vim.validate({ namespace = { namespace, 'n' }, @@ -908,7 +979,7 @@ end --- Get namespace metadata. --- ---@param namespace integer Diagnostic namespace ----@return vim.diagnostic.NS (table) Namespace metadata +---@return vim.diagnostic.NS : Namespace metadata function M.get_namespace(namespace) vim.validate({ namespace = { namespace, 'n' } }) if not all_namespaces[namespace] then @@ -933,22 +1004,21 @@ end --- Get current diagnostic namespaces. --- ----@return table A list of active diagnostic namespaces |vim.diagnostic|. +---@return table : List of active diagnostic namespaces |vim.diagnostic|. function M.get_namespaces() return vim.deepcopy(all_namespaces, true) end --- Get current diagnostics. --- ---- Modifying diagnostics in the returned table has no effect. To set diagnostics in a buffer, use |vim.diagnostic.set()|. +--- Modifying diagnostics in the returned table has no effect. +--- To set diagnostics in a buffer, use |vim.diagnostic.set()|. --- ---@param bufnr integer? Buffer number to get diagnostics from. Use 0 for ---- current buffer or nil for all buffers. ----@param opts? vim.diagnostic.GetOpts (table) A table with the following keys: ---- - namespace: (number) Limit diagnostics to the given namespace. ---- - lnum: (number) Limit diagnostics to the given line number. ---- - severity: See |diagnostic-severity|. ----@return vim.Diagnostic[] table A list of diagnostic items |diagnostic-structure|. Keys `bufnr`, `end_lnum`, `end_col`, and `severity` are guaranteed to be present. +--- current buffer or nil for all buffers. +---@param opts? vim.diagnostic.GetOpts +---@return vim.Diagnostic[] : Fields `bufnr`, `end_lnum`, `end_col`, and `severity` +--- are guaranteed to be present. function M.get(bufnr, opts) vim.validate({ bufnr = { bufnr, 'n', true }, @@ -962,11 +1032,9 @@ end --- ---@param bufnr? integer Buffer number to get diagnostics from. Use 0 for --- current buffer or nil for all buffers. ----@param opts? table A table with the following keys: ---- - namespace: (number) Limit diagnostics to the given namespace. ---- - lnum: (number) Limit diagnostics to the given line number. ---- - severity: See |diagnostic-severity|. ----@return table A table with actually present severity values as keys (see |diagnostic-severity|) and integer counts as values. +---@param opts? vim.diagnostic.GetOpts +---@return table : Table with actually present severity values as keys +--- (see |diagnostic-severity|) and integer counts as values. function M.count(bufnr, opts) vim.validate({ bufnr = { bufnr, 'n', true }, @@ -984,8 +1052,8 @@ end --- Get the previous diagnostic closest to the cursor position. --- ----@param opts? vim.diagnostic.GotoOpts (table) See |vim.diagnostic.goto_next()| ----@return vim.Diagnostic? Previous diagnostic +---@param opts? vim.diagnostic.GotoOpts +---@return vim.Diagnostic? : Previous diagnostic function M.get_prev(opts) opts = opts or {} @@ -998,9 +1066,9 @@ end --- Return the position of the previous diagnostic in the current buffer. --- ----@param opts? vim.diagnostic.GotoOpts (table) See |vim.diagnostic.goto_next()| ----@return table|false: Previous diagnostic position as a (row, col) tuple or false if there is no ---- prior diagnostic +---@param opts? vim.diagnostic.GotoOpts +---@return table|false: Previous diagnostic position as a `(row, col)` tuple +--- or `false` if there is no prior diagnostic. function M.get_prev_pos(opts) local prev = M.get_prev(opts) if not prev then @@ -1011,14 +1079,14 @@ function M.get_prev_pos(opts) end --- Move to the previous diagnostic in the current buffer. ----@param opts? vim.diagnostic.GotoOpts (table) See |vim.diagnostic.goto_next()| +---@param opts? vim.diagnostic.GotoOpts function M.goto_prev(opts) return diagnostic_move_pos(opts, M.get_prev_pos(opts)) end --- Get the next diagnostic closest to the cursor position. --- ----@param opts? vim.diagnostic.GotoOpts (table) See |vim.diagnostic.goto_next()| +---@param opts? vim.diagnostic.GotoOpts ---@return vim.Diagnostic? : Next diagnostic function M.get_next(opts) opts = opts or {} @@ -1032,8 +1100,8 @@ end --- Return the position of the next diagnostic in the current buffer. --- ----@param opts? vim.diagnostic.GotoOpts (table) See |vim.diagnostic.goto_next()| ----@return table|false : Next diagnostic position as a (row, col) tuple or false if no next +---@param opts? vim.diagnostic.GotoOpts +---@return table|false : Next diagnostic position as a `(row, col)` tuple or false if no next --- diagnostic. function M.get_next_pos(opts) local next = M.get_next(opts) @@ -1046,7 +1114,6 @@ end --- A table with the following keys: --- @class vim.diagnostic.GetOpts ---- @inlinedoc --- --- Limit diagnostics to the given namespace. --- @field namespace? integer @@ -1059,13 +1126,10 @@ end --- Configuration table with the following keys: --- @class vim.diagnostic.GotoOpts : vim.diagnostic.GetOpts ---- @inlinedoc --- ---- Only consider diagnostics from the given namespace. ---- @field namespace integer ---- ---- Cursor position as a (row, col) tuple. ---- See |nvim_win_get_cursor()|. Defaults to the current cursor position. +--- Cursor position as a `(row, col)` tuple. +--- See |nvim_win_get_cursor()|. +--- (default: current cursor position) --- @field cursor_position? {[1]:integer,[2]:integer} --- --- Whether to loop around file or not. Similar to 'wrapscan'. @@ -1075,11 +1139,10 @@ end --- See |diagnostic-severity|. --- @field severity vim.diagnostic.Severity --- ---- If "true", call |vim.diagnostic.open_float()| ---- after moving. If a table, pass the table as the {opts} parameter ---- to |vim.diagnostic.open_float()|. Unless overridden, the float will show ---- diagnostics at the new cursor position (as if "cursor" were passed to ---- the "scope" option). +--- If `true`, call |vim.diagnostic.open_float()| after moving. +--- If a table, pass the table as the {opts} parameter to |vim.diagnostic.open_float()|. +--- Unless overridden, the float will show diagnostics at the new cursor +--- position (as if "cursor" were passed to the "scope" option). --- (default: `true`) --- @field float? boolean|vim.diagnostic.Opts.Float --- @@ -1141,7 +1204,7 @@ M.handlers.signs = { -- 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 + if opts.signs and not opts.signs.text and not opts.signs.numhl then for _, v in ipairs({ 'Error', 'Warn', 'Info', 'Hint' }) do local name = string.format('DiagnosticSign%s', v) local sign = vim.fn.sign_getdefined(name)[1] @@ -1476,7 +1539,7 @@ end --- without saving them or to display only a subset of --- diagnostics. May not be used when {namespace} --- or {bufnr} is nil. ----@param opts? vim.diagnostic.Opts (table) Display options. See |vim.diagnostic.config()|. +---@param opts? vim.diagnostic.Opts Display options. function M.show(namespace, bufnr, diagnostics, opts) vim.validate({ namespace = { namespace, 'n', true }, @@ -1552,46 +1615,7 @@ end --- Show diagnostics in a floating window. --- ----@param opts vim.diagnostic.Opts.Float? (table?) Configuration table with the same keys ---- as |vim.lsp.util.open_floating_preview()| in addition to the following: ---- - bufnr: (number) Buffer number to show diagnostics from. ---- Defaults to the current buffer. ---- - namespace: (number) Limit diagnostics to the given namespace ---- - scope: (string, default "line") Show diagnostics from the whole buffer ("buffer"), ---- the current cursor line ("line"), or the current cursor position ("cursor"). ---- Shorthand versions are also accepted ("c" for "cursor", "l" for "line", "b" ---- for "buffer"). ---- - pos: (number or table) If {scope} is "line" or "cursor", use this position rather ---- than the cursor position. If a number, interpreted as a line number; ---- otherwise, a (row, col) tuple. ---- - severity_sort: (default false) Sort diagnostics by severity. Overrides the setting ---- from |vim.diagnostic.config()|. ---- - severity: See |diagnostic-severity|. Overrides the setting ---- from |vim.diagnostic.config()|. ---- - header: (string or table) String to use as the header for the floating window. If a ---- table, it is interpreted as a [text, hl_group] tuple. Overrides the setting ---- from |vim.diagnostic.config()|. ---- - source: (boolean or string) Include the diagnostic source in the message. ---- Use "if_many" to only show sources if there is more than one source of ---- diagnostics in the buffer. Otherwise, any truthy value means to always show ---- the diagnostic source. Overrides the setting from |vim.diagnostic.config()|. ---- - 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. ---- Overrides the setting from |vim.diagnostic.config()|. ---- - prefix: (function, string, or table) Prefix each diagnostic in the floating ---- window. If a function, it must have the signature (diagnostic, i, ---- total) -> (string, string), where {i} is the index of the diagnostic ---- being evaluated and {total} is the total number of diagnostics ---- displayed in the window. The function should return a string which ---- is prepended to each diagnostic in the window as well as an ---- (optional) highlight group which will be used to highlight the ---- prefix. If {prefix} is a table, it is interpreted as a [text, ---- hl_group] tuple as in |nvim_echo()|; otherwise, if {prefix} is a ---- string, it is prepended to each diagnostic in the window with no ---- highlight. ---- 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()|. +---@param opts vim.diagnostic.Opts.Float? ---@return integer? float_bufnr ---@return integer? win_id function M.open_float(opts, ...) @@ -1963,8 +1987,7 @@ end --- WARNING filename:27:3: Variable 'foo' does not exist --- ``` --- ---- This can be parsed into a diagnostic |diagnostic-structure| ---- with: +--- This can be parsed into |vim.Diagnostic| structure with: --- --- ```lua --- local s = "WARNING filename:27:3: Variable 'foo' does not exist" @@ -1975,14 +1998,14 @@ end --- ---@param str string String to parse diagnostics from. ---@param pat string Lua pattern with capture groups. ----@param groups string[] List of fields in a |diagnostic-structure| to +---@param groups string[] List of fields in a |vim.Diagnostic| structure to --- associate with captures from {pat}. ---@param severity_map table A table mapping the severity field from {groups} --- with an item from |vim.diagnostic.severity|. ---@param defaults table? Table of default values for any fields not listed in {groups}. --- When omitted, numeric values default to 0 and "severity" defaults to --- ERROR. ----@return vim.Diagnostic?: |diagnostic-structure| or `nil` if {pat} fails to match {str}. +---@return vim.Diagnostic?: |vim.Diagnostic| structure or `nil` if {pat} fails to match {str}. function M.match(str, pat, groups, severity_map, defaults) vim.validate({ str = { str, 's' }, @@ -2030,8 +2053,8 @@ local errlist_type_map = { --- Convert a list of diagnostics to a list of quickfix items that can be --- passed to |setqflist()| or |setloclist()|. --- ----@param diagnostics vim.Diagnostic[] List of diagnostics |diagnostic-structure|. ----@return table[] of quickfix list items |setqflist-what| +---@param diagnostics vim.Diagnostic[] +---@return table[] : Quickfix list items |setqflist-what| function M.toqflist(diagnostics) vim.validate({ diagnostics = { @@ -2071,7 +2094,7 @@ end --- Convert a list of quickfix items to a list of diagnostics. --- ---@param list table[] List of quickfix items from |getqflist()| or |getloclist()|. ----@return vim.Diagnostic[] array of |diagnostic-structure| +---@return vim.Diagnostic[] function M.fromqflist(list) vim.validate({ list = { diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua index 8ebf4de3cb..ef5d9d7cff 100644 --- a/runtime/lua/vim/lsp.lua +++ b/runtime/lua/vim/lsp.lua @@ -961,16 +961,15 @@ end --- --- Calls |vim.lsp.buf_request_all()| but blocks Nvim while awaiting the result. --- Parameters are the same as |vim.lsp.buf_request_all()| but the result is ---- different. Waits a maximum of {timeout_ms} (default 1000) ms. +--- different. Waits a maximum of {timeout_ms}. --- ----@param bufnr (integer) Buffer handle, or 0 for current. ----@param method (string) LSP method name ----@param params (table|nil) Parameters to send to the server ----@param timeout_ms (integer|nil) Maximum time in milliseconds to wait for a ---- result. Defaults to 1000 ---- ----@return table|nil (table) result Map of client_id:request_result. ----@return string|nil err On timeout, cancel, or error, `err` is a string describing the failure reason, and `result` is nil. +---@param bufnr integer Buffer handle, or 0 for current. +---@param method string LSP method name +---@param params table? Parameters to send to the server +---@param timeout_ms integer? Maximum time in milliseconds to wait for a result. +--- (default: `1000`) +---@return table? result Map of client_id:request_result. +---@return string? err On timeout, cancel, or error, `err` is a string describing the failure reason, and `result` is nil. function lsp.buf_request_sync(bufnr, method, params, timeout_ms) local request_results diff --git a/runtime/lua/vim/lsp/client.lua b/runtime/lua/vim/lsp/client.lua index 0f47c57cd5..6dd898bea7 100644 --- a/runtime/lua/vim/lsp/client.lua +++ b/runtime/lua/vim/lsp/client.lua @@ -11,6 +11,24 @@ local validate = vim.validate --- @alias vim.lsp.client.on_exit_cb fun(code: integer, signal: integer, client_id: integer) --- @alias vim.lsp.client.before_init_cb fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig) +--- @class vim.lsp.Client.Flags +--- @inlinedoc +--- +--- Allow using incremental sync for buffer edits +--- (defailt: `true`) +--- @field allow_incremental_sync? boolean +--- +--- Debounce `didChange` notifications to the server by the given number in milliseconds. +--- No debounce occurs if `nil`. +--- (default: `150`) +--- @field debounce_text_changes integer +--- +--- 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. +--- (default: `false`) +--- @field exit_timeout integer|false + --- @class vim.lsp.ClientConfig --- command string[] that launches the language --- server (treated as in |jobstart()|, must be absolute or on `$PATH`, shell constructs like @@ -55,8 +73,8 @@ local validate = vim.validate --- Map of language server method names to |lsp-handler| --- @field handlers? table --- ---- Map with language server specific settings. These are returned to the language server if ---- requested via `workspace/configuration`. Keys are case-sensitive. +--- Map with language server specific settings. +--- See the {settings} in |vim.lsp.Client|. --- @field settings? table --- --- Table that maps string of clientside commands to user-defined functions. @@ -87,36 +105,29 @@ local validate = vim.validate --- Callback invoked before the LSP "initialize" phase, where `params` contains the parameters --- being sent to the server and `config` is the config that was passed to |vim.lsp.start_client()|. --- You can use this to modify parameters before they are sent. ---- @field before_init? vim.lsp.client.before_init_cb +--- @field before_init? fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig) --- --- Callback invoked after LSP "initialize", where `result` is a table of `capabilities` --- and anything else the server may send. For example, clangd sends --- `initialize_result.offsetEncoding` if `capabilities.offsetEncoding` was sent to it. --- You can only modify the `client.offset_encoding` here before any notifications are sent. ---- @field on_init? elem_or_list +--- @field on_init? elem_or_list --- --- Callback invoked on client exit. --- - code: exit code of the process --- - signal: number describing the signal used to terminate (if any) --- - client_id: client handle ---- @field on_exit? elem_or_list +--- @field on_exit? elem_or_list --- --- Callback invoked when client attaches to a buffer. ---- @field on_attach? elem_or_list +--- @field on_attach? elem_or_list --- --- Passed directly to the language server in the initialize request. Invalid/empty values will --- (default: "off") --- @field trace? 'off'|'messages'|'verbose' --- --- 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. ---- @field flags? table +--- @field flags? vim.lsp.Client.Flags --- --- Directory where the LSP server will base its workspaceFolders, rootUri, and rootPath on initialization. --- @field root_dir? string @@ -189,8 +200,14 @@ local validate = vim.validate --- Client commands take precedence over the global command registry. --- @field commands table --- +--- Map with language server specific settings. These are returned to the +--- language server if requested via `workspace/configuration`. Keys are +--- case-sensitive. --- @field settings table ---- @field flags table +--- +--- A table with flags for the client. The current (experimental) flags are: +--- @field flags vim.lsp.Client.Flags +--- --- @field get_language_id fun(bufnr: integer, filetype: string): string --- --- The capabilities provided by the client (editor or tool) diff --git a/runtime/lua/vim/lsp/diagnostic.lua b/runtime/lua/vim/lsp/diagnostic.lua index 6156821093..e4620897ac 100644 --- a/runtime/lua/vim/lsp/diagnostic.lua +++ b/runtime/lua/vim/lsp/diagnostic.lua @@ -321,7 +321,7 @@ end ---@param _ lsp.ResponseError? ---@param result lsp.DocumentDiagnosticReport ---@param ctx lsp.HandlerContext ----@param config table Configuration table (see |vim.diagnostic.config()|). +---@param config vim.diagnostic.Opts Configuration table (see |vim.diagnostic.config()|). function M.on_diagnostic(_, result, ctx, config) if result == nil or result.kind == 'unchanged' then return diff --git a/runtime/lua/vim/lsp/semantic_tokens.lua b/runtime/lua/vim/lsp/semantic_tokens.lua index 92546e8520..20ac0a125f 100644 --- a/runtime/lua/vim/lsp/semantic_tokens.lua +++ b/runtime/lua/vim/lsp/semantic_tokens.lua @@ -572,7 +572,7 @@ local M = {} --- ---@param bufnr integer ---@param client_id integer ----@param opts (nil|table) Optional keyword arguments +---@param opts? table Optional keyword arguments --- - debounce (integer, default: 200): Debounce token requests --- to the server by the given number in milliseconds function M.start(bufnr, client_id, opts) diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua index ec70630df3..18d7c8b13e 100644 --- a/runtime/lua/vim/shared.lua +++ b/runtime/lua/vim/shared.lua @@ -102,7 +102,7 @@ end --- @param s string String to split --- @param sep string Separator or pattern --- @param opts? vim.gsplit.Opts Keyword arguments |kwargs|: ---- @return fun():string|nil (function) Iterator over the split components +--- @return fun():string? : Iterator over the split components function vim.gsplit(s, sep, opts) local plain --- @type boolean? local trimempty = false @@ -245,8 +245,8 @@ end --- Apply a function to all values of a table. --- ---@generic T ----@param func fun(value: T): any (function) Function ----@param t table (table) Table +---@param func fun(value: T): any Function +---@param t table Table ---@return table : Table of transformed values function vim.tbl_map(func, t) vim.validate({ func = { func, 'c' }, t = { t, 't' } }) @@ -570,8 +570,10 @@ end --- ---@see Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua --- ----@param t table Dict-like table ----@return function # |for-in| iterator over sorted keys and their values +---@generic T: table, K, V +---@param t T Dict-like table +---@return fun(table: table, index?: K):K, V # |for-in| iterator over sorted keys and their values +---@return T function vim.spairs(t) vim.validate({ t = { t, 't' } }) --- @cast t table @@ -1018,7 +1020,7 @@ do --- - |Ringbuf:clear()| --- ---@param size integer - ---@return vim.Ringbuf ringbuf (table) + ---@return vim.Ringbuf ringbuf function vim.ringbuf(size) local ringbuf = { _items = {}, diff --git a/scripts/gen_vimdoc.lua b/scripts/gen_vimdoc.lua index 8e2ff8193c..22df411a35 100755 --- a/scripts/gen_vimdoc.lua +++ b/scripts/gen_vimdoc.lua @@ -536,7 +536,8 @@ local function render_fields_or_params(xs, generics, classes, exclude_types) end --- @param class nvim.luacats.parser.class -local function render_class(class) +--- @param classes table +local function render_class(class, classes) if class.access or class.nodoc or class.inlinedoc then return end @@ -548,13 +549,14 @@ local function render_class(class) if class.parent then local txt = fmt('Extends: |%s|', class.parent) table.insert(ret, md_to_vimdoc(txt, INDENTATION, INDENTATION, TEXT_WIDTH)) + table.insert(ret, '\n') end if class.desc then table.insert(ret, md_to_vimdoc(class.desc, INDENTATION, INDENTATION, TEXT_WIDTH)) end - local fields_txt = render_fields_or_params(class.fields) + local fields_txt = render_fields_or_params(class.fields, nil, classes) if not fields_txt:match('^%s*$') then table.insert(ret, '\n Fields: ~\n') table.insert(ret, fields_txt) @@ -564,13 +566,12 @@ local function render_class(class) return table.concat(ret) end ---- @param cls table -local function render_classes(cls) +--- @param classes table +local function render_classes(classes) local ret = {} --- @type string[] - --- @diagnostic disable-next-line:no-unknown - for _, class in vim.spairs(cls) do - ret[#ret + 1] = render_class(class) + for _, class in vim.spairs(classes) do + ret[#ret + 1] = render_class(class, classes) end return table.concat(ret) diff --git a/scripts/luacats_grammar.lua b/scripts/luacats_grammar.lua index 0beb1d2352..158541dc77 100644 --- a/scripts/luacats_grammar.lua +++ b/scripts/luacats_grammar.lua @@ -170,7 +170,7 @@ local grammar = P { ltype = parenOpt(v.ty_union), ty_union = v.ty_opt * rep(Pf('|') * v.ty_opt), - ty = v.ty_fun + ident + v.ty_table + literal, + ty = v.ty_fun + ident + v.ty_table + literal + paren(v.ty), ty_param = Pf('<') * comma1(v.ltype) * fill * P('>'), ty_opt = v.ty * opt(v.ty_param) * opt(P('[]')) * opt(P('?')), ty_index = (Pf('[') * v.ltype * Pf(']')), diff --git a/test/functional/script/luacats_grammar_spec.lua b/test/functional/script/luacats_grammar_spec.lua index 931fe42dd0..0fc2e4b95a 100644 --- a/test/functional/script/luacats_grammar_spec.lua +++ b/test/functional/script/luacats_grammar_spec.lua @@ -130,4 +130,13 @@ describe('luacats grammar', function() type = 'b', desc = 'desc', }) + + test( + '@field prefix? string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)', + { + kind = 'field', + name = 'prefix?', + type = 'string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)', + } + ) end)