pt
/
neovim
mirror of https://github.com/neovim/neovim.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

fix(doc): improve doc generation of types using lpeg 

Added a lpeg grammar for LuaCATS and use it in lua2dox.lua
This commit is contained in:
Lewis Russell 2024-01-09 17:36:46 +00:00 committed by Lewis Russell
parent a767c046f4
commit 2f9ee9b6cf
20 changed files with 1239 additions and 925 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
runtime/doc/api.txt
View File

@ -3381,9 +3381,8 @@ nvim_create_augroup({name}, {*opts}) *nvim_create_augroup()*
• |autocmd-groups|
nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()*
Creates an |autocommand| event handler, defined by `callback` (Lua
function or Vimscript function name string) or `command` (Ex command
string).
Creates an |autocommand| event handler, defined by `callback` (Lua function
or Vimscript function name string) or `command` (Ex command string).
Example using Lua callback: >lua
vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {

132
runtime/doc/diagnostic.txt
View File

@ -390,7 +390,7 @@ config({opts}, {namespace}) *vim.diagnostic.config()*
any of the above.
Parameters: ~
• {opts} (table|nil) When omitted or "nil", retrieve the current
• {opts} (`table?`) When omitted or "nil", retrieve the current
configuration. Otherwise, a configuration table with the
following keys:
• underline: (default true) Use underline for
@ -475,55 +475,55 @@ config({opts}, {namespace}) *vim.diagnostic.config()*
severities are displayed before lower severities (e.g.
ERROR is displayed before WARN). Options:
• reverse: (boolean) Reverse sort order
• {namespace} (integer|nil) Update the options for the given namespace.
• {namespace} (`integer?`) Update the options for the given namespace.
When omitted, update the global diagnostic options.
Return: ~
(table|nil) table of current diagnostic config if `opts` is omitted.
(`table?`) table of current diagnostic config if `opts` is omitted.
count({bufnr}, {opts}) *vim.diagnostic.count()*
Get current diagnostics count.
Parameters: ~
• {bufnr} (integer|nil) Buffer number to get diagnostics from. Use 0
for current buffer or nil for all buffers.
• {opts} (table|nil) A table with the following keys:
• {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|.
Return: ~
(table) A table with actually present severity values as keys (see
(`table`) A table with actually present severity values as keys (see
|diagnostic-severity|) and integer counts as values.
disable({bufnr}, {namespace}) *vim.diagnostic.disable()*
Disable diagnostics in the given buffer.
Parameters: ~
• {bufnr} (integer|nil) Buffer number, or 0 for current buffer.
When omitted, disable diagnostics in all buffers.
• {namespace} (integer|nil) Only disable diagnostics for the given
• {bufnr} (`integer?`) Buffer number, or 0 for current buffer. When
omitted, disable diagnostics in all buffers.
• {namespace} (`integer?`) Only disable diagnostics for the given
namespace.
enable({bufnr}, {namespace}) *vim.diagnostic.enable()*
Enable diagnostics in the given buffer.
Parameters: ~
• {bufnr} (integer|nil) Buffer number, or 0 for current buffer.
When omitted, enable diagnostics in all buffers.
• {namespace} (integer|nil) Only enable diagnostics for the given
• {bufnr} (`integer?`) Buffer number, or 0 for current buffer. When
omitted, enable diagnostics in all buffers.
• {namespace} (`integer?`) Only enable diagnostics for the given
namespace.
fromqflist({list}) *vim.diagnostic.fromqflist()*
Convert a list of quickfix items to a list of diagnostics.
Parameters: ~
• {list} table[] List of quickfix items from |getqflist()| or
• {list} (`table[]`) List of quickfix items from |getqflist()| or
|getloclist()|.
Return: ~
Diagnostic [] array of |diagnostic-structure|
(`Diagnostic[]`) array of |diagnostic-structure|
get({bufnr}, {opts}) *vim.diagnostic.get()*
Get current diagnostics.
@ -532,77 +532,77 @@ get({bufnr}, {opts}) *vim.diagnostic.get()*
diagnostics in a buffer, use |vim.diagnostic.set()|.
Parameters: ~
• {bufnr} (integer|nil) Buffer number to get diagnostics from. Use 0
for current buffer or nil for all buffers.
• {opts} (table|nil) A table with the following keys:
• {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|.
Return: ~
Diagnostic [] table A list of diagnostic items |diagnostic-structure|.
Keys `bufnr` , `end_lnum` , `end_col` , and `severity` are
(`Diagnostic[]`) table A list of diagnostic items
|diagnostic-structure|. Keys `bufnr` , `end_lnum` , `end_col` , and `severity` are
guaranteed to be present.
get_namespace({namespace}) *vim.diagnostic.get_namespace()*
Get namespace metadata.
Parameters: ~
• {namespace} (integer) Diagnostic namespace
• {namespace} (`integer`) Diagnostic namespace
Return: ~
(table) Namespace metadata
(`table`) Namespace metadata
get_namespaces() *vim.diagnostic.get_namespaces()*
Get current diagnostic namespaces.
Return: ~
(table) A list of active diagnostic namespaces |vim.diagnostic|.
(`table`) A 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|nil) See |vim.diagnostic.goto_next()|
• {opts} (`table?`) See |vim.diagnostic.goto_next()|
Return: ~
Diagnostic|nil Next diagnostic
(`Diagnostic?`) Next diagnostic
get_next_pos({opts}) *vim.diagnostic.get_next_pos()*
Return the position of the next diagnostic in the current buffer.
Parameters: ~
• {opts} (table|nil) See |vim.diagnostic.goto_next()|
• {opts} (`table?`) See |vim.diagnostic.goto_next()|
Return: ~
table|false Next diagnostic position as a (row, col) tuple or false if
no next diagnostic.
(`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} nil|table See |vim.diagnostic.goto_next()|
• {opts} (`table?`) See |vim.diagnostic.goto_next()|
Return: ~
Diagnostic|nil Previous diagnostic
(`Diagnostic?`) Previous diagnostic
get_prev_pos({opts}) *vim.diagnostic.get_prev_pos()*
Return the position of the previous diagnostic in the current buffer.
Parameters: ~
• {opts} (table|nil) See |vim.diagnostic.goto_next()|
• {opts} (`table?`) See |vim.diagnostic.goto_next()|
Return: ~
table|false Previous diagnostic position as a (row, col) tuple or
(`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|nil) Configuration table with the following keys:
• {opts} (`table?`) Configuration table with the following keys:
• namespace: (number) Only consider diagnostics from the given
namespace.
• cursor_position: (cursor position) Cursor position as a
@ -623,7 +623,7 @@ goto_prev({opts}) *vim.diagnostic.goto_prev()*
Move to the previous diagnostic in the current buffer.
Parameters: ~
• {opts} (table|nil) See |vim.diagnostic.goto_next()|
• {opts} (`table?`) See |vim.diagnostic.goto_next()|
hide({namespace}, {bufnr}) *vim.diagnostic.hide()*
Hide currently displayed diagnostics.
@ -636,22 +636,22 @@ hide({namespace}, {bufnr}) *vim.diagnostic.hide()*
|vim.diagnostic.disable()|.
Parameters: ~
• {namespace} (integer|nil) Diagnostic namespace. When omitted, hide
• {namespace} (`integer?`) Diagnostic namespace. When omitted, hide
diagnostics from all namespaces.
• {bufnr} (integer|nil) Buffer number, or 0 for current buffer.
When omitted, hide diagnostics in all buffers.
• {bufnr} (`integer?`) Buffer number, or 0 for current buffer. When
omitted, hide diagnostics in all buffers.
is_disabled({bufnr}, {namespace}) *vim.diagnostic.is_disabled()*
Check whether diagnostics are disabled in a given buffer.
Parameters: ~
• {bufnr} (integer|nil) Buffer number, or 0 for current buffer.
• {namespace} (integer|nil) Diagnostic namespace. When omitted, checks
if all diagnostics are disabled in {bufnr}. Otherwise,
only checks if diagnostics from {namespace} are disabled.
• {bufnr} (`integer?`) Buffer number, or 0 for current buffer.
• {namespace} (`integer?`) Diagnostic namespace. When omitted, checks if
all diagnostics are disabled in {bufnr}. Otherwise, only
checks if diagnostics from {namespace} are disabled.
Return: ~
(boolean)
(`boolean`)
*vim.diagnostic.match()*
match({str}, {pat}, {groups}, {severity_map}, {defaults})
@ -669,25 +669,25 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults})
<
Parameters: ~
• {str} (string) String to parse diagnostics from.
• {pat} (string) Lua pattern with capture groups.
• {groups} (table) List of fields in a |diagnostic-structure| to
associate with captures from {pat}.
• {severity_map} (table) A table mapping the severity field from
• {str} (`string`) String to parse diagnostics from.
• {pat} (`string`) Lua pattern with capture groups.
• {groups} (`table`) List of fields in a |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|nil) Table of default values for any fields not
• {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: ~
Diagnostic|nil: |diagnostic-structure| or `nil` if {pat} fails to
match {str}.
(`Diagnostic?`) |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|nil) Configuration table with the same keys as
• {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.
@ -737,7 +737,7 @@ open_float({opts}, {...}) *vim.diagnostic.open_float()*
from |vim.diagnostic.config()|.
Return: ~
integer|nil, integer|nil: ({float_bufnr}, {win_id})
(`integer?, integer?`) ({float_bufnr}, {win_id})
reset({namespace}, {bufnr}) *vim.diagnostic.reset()*
Remove all diagnostics from the given namespace.
@ -748,27 +748,27 @@ reset({namespace}, {bufnr}) *vim.diagnostic.reset()*
re-displayed, use |vim.diagnostic.hide()|.
Parameters: ~
• {namespace} (integer|nil) Diagnostic namespace. When omitted, remove
• {namespace} (`integer?`) Diagnostic namespace. When omitted, remove
diagnostics from all namespaces.
• {bufnr} (integer|nil) Remove diagnostics for the given buffer.
• {bufnr} (`integer?`) Remove diagnostics for the given buffer.
When omitted, diagnostics are removed for all buffers.
set({namespace}, {bufnr}, {diagnostics}, {opts}) *vim.diagnostic.set()*
Set diagnostics for the given namespace and buffer.
Parameters: ~
• {namespace} (integer) The diagnostic namespace
• {bufnr} (integer) Buffer number
• {diagnostics} (table) A list of diagnostic items
• {namespace} (`integer`) The diagnostic namespace
• {bufnr} (`integer`) Buffer number
• {diagnostics} (`table`) A list of diagnostic items
|diagnostic-structure|
• {opts} (table|nil) Display options to pass to
• {opts} (`table?`) Display options to pass to
|vim.diagnostic.show()|
setloclist({opts}) *vim.diagnostic.setloclist()*
Add buffer diagnostics to the location list.
Parameters: ~
• {opts} (table|nil) Configuration table with the following keys:
• {opts} (`table?`) Configuration table with the following keys:
• namespace: (number) Only add diagnostics from the given
namespace.
• winnr: (number, default 0) Window number to set location
@ -783,7 +783,7 @@ setqflist({opts}) *vim.diagnostic.setqflist()*
Add all diagnostics to the quickfix list.
Parameters: ~
• {opts} (table|nil) Configuration table with the following keys:
• {opts} (`table?`) Configuration table with the following keys:
• namespace: (number) Only add diagnostics from the given
namespace.
• open: (boolean, default true) Open quickfix list after
@ -797,17 +797,17 @@ show({namespace}, {bufnr}, {diagnostics}, {opts})
Display diagnostics for the given namespace and buffer.
Parameters: ~
• {namespace} (integer|nil) Diagnostic namespace. When omitted, show
• {namespace} (`integer?`) Diagnostic namespace. When omitted, show
diagnostics from all namespaces.
• {bufnr} (integer|nil) Buffer number, or 0 for current buffer.
• {bufnr} (`integer?`) Buffer number, or 0 for current buffer.
When omitted, show diagnostics in all buffers.
• {diagnostics} (table|nil) The diagnostics to display. When omitted,
• {diagnostics} (`table?`) The diagnostics to display. When omitted,
use the saved diagnostics for the given namespace and
buffer. This can be used to display a list of
diagnostics without saving them or to display only a
subset of diagnostics. May not be used when {namespace}
or {bufnr} is nil.
• {opts} (table|nil) Display options. See
• {opts} (`table?`) Display options. See
|vim.diagnostic.config()|.
toqflist({diagnostics}) *vim.diagnostic.toqflist()*
@ -815,9 +815,9 @@ toqflist({diagnostics}) *vim.diagnostic.toqflist()*
passed to |setqflist()| or |setloclist()|.
Parameters: ~
• {diagnostics} (table) List of diagnostics |diagnostic-structure|.
• {diagnostics} (`table`) List of diagnostics |diagnostic-structure|.
Return: ~
table[] of quickfix list items |setqflist-what|
(`table[]`) of quickfix list items |setqflist-what|
vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:

466
runtime/doc/lsp.txt
View File

File diff suppressed because it is too large Load Diff

759
runtime/doc/lua.txt
View File

File diff suppressed because it is too large Load Diff

233
runtime/doc/treesitter.txt
View File

@ -567,10 +567,10 @@ foldexpr({lnum}) *vim.treesitter.foldexpr()*
<
Parameters: ~
• {lnum} (integer|nil) Line number to calculate fold level for
• {lnum} (`integer?`) Line number to calculate fold level for
Return: ~
(string)
(`string`)
foldtext() *vim.treesitter.foldtext()*
Returns the highlighted content of the first line of the fold or falls
@ -580,17 +580,17 @@ foldtext() *vim.treesitter.foldtext()*
<
Return: ~
`{ [1]: string, [2]: string[] }[]` | string
(`{ [1]: string, [2]: string[] }[]|string`)
*vim.treesitter.get_captures_at_cursor()*
get_captures_at_cursor({winnr})
Returns a list of highlight capture names under the cursor
Parameters: ~
• {winnr} (integer|nil) Window handle or 0 for current window (default)
• {winnr} (`integer?`) Window handle or 0 for current window (default)
Return: ~
string[] List of capture names
(`string[]`) List of capture names
*vim.treesitter.get_captures_at_pos()*
get_captures_at_pos({bufnr}, {row}, {col})
@ -601,12 +601,13 @@ get_captures_at_pos({bufnr}, {row}, {col})
if none are defined).
Parameters: ~
• {bufnr} (integer) Buffer number (0 for current buffer)
• {row} (integer) Position row
• {col} (integer) Position column
• {bufnr} (`integer`) Buffer number (0 for current buffer)
• {row} (`integer`) Position row
• {col} (`integer`) Position column
Return: ~
table[] List of captures `{ capture = "name", metadata = { ... } }`
(`table[]`) List of captures `{ capture = "name", metadata = { ... }
}`
get_node({opts}) *vim.treesitter.get_node()*
Returns the smallest named node at the given position
@ -618,7 +619,7 @@ get_node({opts}) *vim.treesitter.get_node()*
<
Parameters: ~
• {opts} (table|nil) Optional keyword arguments:
• {opts} (`table?`) Optional keyword arguments:
• bufnr integer|nil Buffer number (nil or 0 for current
buffer)
• pos table|nil 0-indexed (row, col) tuple. Defaults to cursor
@ -630,35 +631,35 @@ get_node({opts}) *vim.treesitter.get_node()*
true)
Return: ~
|TSNode| | nil Node at the given position
(`TSNode?`) Node at the given position
get_node_range({node_or_range}) *vim.treesitter.get_node_range()*
Returns the node's range or an unpacked range table
Parameters: ~
• {node_or_range} (|TSNode| | table) Node or table of positions
• {node_or_range} (`TSNode|table`) Node or table of positions
Return (multiple): ~
(integer) start_row
(integer) start_col
(integer) end_row
(integer) end_col
(`integer`) start_row
(`integer`) start_col
(`integer`) end_row
(`integer`) end_col
*vim.treesitter.get_node_text()*
get_node_text({node}, {source}, {opts})
Gets the text corresponding to a given node
Parameters: ~
• {node} |TSNode|
• {source} (integer|string) Buffer or string from which the {node} is
• {node} (`TSNode`)
• {source} (`integer|string`) Buffer or string from which the {node} is
extracted
• {opts} (table|nil) Optional parameters.
• {opts} (`table?`) Optional parameters.
• metadata (table) Metadata of a specific capture. This
would be set to `metadata[capture_id]` when using
|vim.treesitter.query.add_directive()|.
Return: ~
(string)
(`string`)
get_parser({bufnr}, {lang}, {opts}) *vim.treesitter.get_parser()*
Returns the parser for a specific buffer and attaches it to the buffer
@ -666,39 +667,39 @@ get_parser({bufnr}, {lang}, {opts}) *vim.treesitter.get_parser()*
If needed, this will create the parser.
Parameters: ~
• {bufnr} (integer|nil) Buffer the parser should be tied to (default:
• {bufnr} (`integer?`) Buffer the parser should be tied to (default:
current buffer)
• {lang} (string|nil) Filetype of this parser (default: buffer
• {lang} (`string?`) Filetype of this parser (default: buffer
filetype)
• {opts} (table|nil) Options to pass to the created language tree
• {opts} (`table?`) Options to pass to the created language tree
Return: ~
|LanguageTree| object to use for parsing
(`LanguageTree`) object to use for parsing
get_range({node}, {source}, {metadata}) *vim.treesitter.get_range()*
Get the range of a |TSNode|. Can also supply {source} and {metadata} to
get the range with directives applied.
Parameters: ~
• {node} |TSNode|
• {source} integer|string|nil Buffer or string from which the {node}
• {node} (`TSNode`)
• {source} (`integer|string?`) Buffer or string from which the {node}
is extracted
• {metadata} TSMetadata|nil
• {metadata} (`TSMetadata?`)
Return: ~
(table)
(`Range6`)
*vim.treesitter.get_string_parser()*
get_string_parser({str}, {lang}, {opts})
Returns a string parser
Parameters: ~
• {str} (string) Text to parse
• {lang} (string) Language of this string
• {opts} (table|nil) Options to pass to the created language tree
• {str} (`string`) Text to parse
• {lang} (`string`) Language of this string
• {opts} (`table?`) Options to pass to the created language tree
Return: ~
|LanguageTree| object to use for parsing
(`LanguageTree`) object to use for parsing
inspect_tree({opts}) *vim.treesitter.inspect_tree()*
Open a window that displays a textual representation of the nodes in the
@ -712,7 +713,7 @@ inspect_tree({opts}) *vim.treesitter.inspect_tree()*
Can also be shown with `:InspectTree`. *:InspectTree*
Parameters: ~
• {opts} (table|nil) Optional options table with the following possible
• {opts} (`table?`) Optional options table with the following possible
keys:
• lang (string|nil): The language of the source buffer. If
omitted, the filetype of the source buffer is used.
@ -732,33 +733,33 @@ is_ancestor({dest}, {source}) *vim.treesitter.is_ancestor()*
Determines whether a node is the ancestor of another
Parameters: ~
• {dest} |TSNode| Possible ancestor
• {source} |TSNode| Possible descendant
• {dest} (`TSNode`) Possible ancestor
• {source} (`TSNode`) Possible descendant
Return: ~
(boolean) True if {dest} is an ancestor of {source}
(`boolean`) True if {dest} is an ancestor of {source}
*vim.treesitter.is_in_node_range()*
is_in_node_range({node}, {line}, {col})
Determines whether (line, col) position is in node range
Parameters: ~
• {node} |TSNode| defining the range
• {line} (integer) Line (0-based)
• {col} (integer) Column (0-based)
• {node} (`TSNode`) defining the range
• {line} (`integer`) Line (0-based)
• {col} (`integer`) Column (0-based)
Return: ~
(boolean) True if the position is in node range
(`boolean`) True if the position is in node range
node_contains({node}, {range}) *vim.treesitter.node_contains()*
Determines if a node contains a range
Parameters: ~
• {node} |TSNode|
• {range} (table)
• {node} (`TSNode`)
• {range} (`table`)
Return: ~
(boolean) True if the {node} contains the {range}
(`boolean`) True if the {node} contains the {range}
start({bufnr}, {lang}) *vim.treesitter.start()*
Starts treesitter highlighting for a buffer
@ -779,16 +780,15 @@ start({bufnr}, {lang}) *vim.treesitter.start()*
<
Parameters: ~
• {bufnr} (integer|nil) Buffer to be highlighted (default: current
• {bufnr} (`integer?`) Buffer to be highlighted (default: current
buffer)
• {lang} (string|nil) Language of the parser (default: buffer
filetype)
• {lang} (`string?`) Language of the parser (default: buffer filetype)
stop({bufnr}) *vim.treesitter.stop()*
Stops treesitter highlighting for a buffer
Parameters: ~
• {bufnr} (integer|nil) Buffer to stop highlighting (default: current
• {bufnr} (`integer?`) Buffer to stop highlighting (default: current
buffer)
@ -802,8 +802,8 @@ add({lang}, {opts}) *vim.treesitter.language.add()*
{path}
Parameters: ~
• {lang} (string) Name of the parser (alphanumerical and `_` only)
• {opts} (table|nil) Options:
• {lang} (`string`) Name of the parser (alphanumerical and `_` only)
• {opts} (`table?`) Options:
• filetype (string|string[]) Default filetype the parser
should be associated with. Defaults to {lang}.
• path (string|nil) Optional path the parser is located at
@ -814,17 +814,17 @@ get_filetypes({lang}) *vim.treesitter.language.get_filetypes()*
Get the filetypes associated with the parser named {lang}.
Parameters: ~
• {lang} (string) Name of parser
• {lang} (`string`) Name of parser
Return: ~
string[] filetypes
(`string[]`) filetypes
get_lang({filetype}) *vim.treesitter.language.get_lang()*
Parameters: ~
• {filetype} (string)
• {filetype} (`string`)
Return: ~
(string|nil)
(`string?`)
inspect({lang}) *vim.treesitter.language.inspect()*
Inspects the provided language.
@ -833,10 +833,10 @@ inspect({lang}) *vim.treesitter.language.inspect()*
names, ...
Parameters: ~
• {lang} (string) Language
• {lang} (`string`) Language
Return: ~
(table)
(`table`)
register({lang}, {filetype}) *vim.treesitter.language.register()*
Register a parser named {lang} to be used for {filetype}(s).
@ -845,8 +845,8 @@ register({lang}, {filetype}) *vim.treesitter.language.register()*
mappings from other filetypes to {lang} will be preserved.
Parameters: ~
• {lang} (string) Name of parser
• {filetype} string|string[] Filetype(s) to associate with lang
• {lang} (`string`) Name of parser
• {filetype} (`string|string[]`) Filetype(s) to associate with lang
==============================================================================
@ -862,9 +862,8 @@ add_directive({name}, {handler}, {force})
`metadata[capture_id].key = value`
Parameters: ~
• {name} (string) Name of the directive, without leading #
• {handler} function(match:table<string,|TSNode|>, pattern:string,
bufnr:integer, predicate:string[], metadata:table)
• {name} (`string`) Name of the directive, without leading #
• {handler} (`function`)
• match: see |treesitter-query|
• node-level data are accessible via `match[capture_id]`
@ -872,19 +871,18 @@ add_directive({name}, {handler}, {force})
• predicate: list of strings containing the full directive
being called, e.g. `(node (#set! conceal "-"))` would get
the predicate `{ "#set!", "conceal", "-" }`
• {force} (boolean|nil)
• {force} (`boolean?`)
*vim.treesitter.query.add_predicate()*
add_predicate({name}, {handler}, {force})
Adds a new predicate to be used in queries
Parameters: ~
• {name} (string) Name of the predicate, without leading #
• {handler} function(match:table<string,|TSNode|>, pattern:string,
bufnr:integer, predicate:string[])
• {name} (`string`) Name of the predicate, without leading #
• {handler} (`function`)
• see |vim.treesitter.query.add_directive()| for argument
meanings
• {force} (boolean|nil)
• {force} (`boolean?`)
edit({lang}) *vim.treesitter.query.edit()*
Opens a live editor to query the buffer you started from.
@ -897,31 +895,32 @@ edit({lang}) *vim.treesitter.query.edit()*
`$VIMRUNTIME/queries/`.
Parameters: ~
• {lang} (string|nil) language to open the query editor for. If
omitted, inferred from the current buffer's filetype.
• {lang} (`string?`) language to open the query editor for. If omitted,
inferred from the current buffer's filetype.
get({lang}, {query_name}) *vim.treesitter.query.get()*
Returns the runtime query {query_name} for {lang}.
Parameters: ~
• {lang} (string) Language to use for the query
• {query_name} (string) Name of the query (e.g. "highlights")
• {lang} (`string`) Language to use for the query
• {query_name} (`string`) Name of the query (e.g. "highlights")
Return: ~
Query|nil Parsed query
(`Query?`) Parsed query
*vim.treesitter.query.get_files()*
get_files({lang}, {query_name}, {is_included})
Gets the list of files used to make up a query
Parameters: ~
• {lang} (string) Language to get query for
• {query_name} (string) Name of the query to load (e.g., "highlights")
• {is_included} (boolean|nil) Internal parameter, most of the time left
• {lang} (`string`) Language to get query for
• {query_name} (`string`) Name of the query to load (e.g.,
"highlights")
• {is_included} (`boolean?`) Internal parameter, most of the time left
as `nil`
Return: ~
string[] query_files List of files to load for given query and
(`string[]`) query_files List of files to load for given query and
language
lint({buf}, {opts}) *vim.treesitter.query.lint()*
@ -940,8 +939,8 @@ lint({buf}, {opts}) *vim.treesitter.query.lint()*
for the `lua` language will be used.
Parameters: ~
• {buf} (integer) Buffer handle
• {opts} (QueryLinterOpts|nil) Optional keyword arguments:
• {buf} (`integer`) Buffer handle
• {opts} (`table?`) Optional keyword arguments:
• langs (string|string[]|nil) Language(s) to use for checking
the query. If multiple languages are specified, queries are
validated for all of them
@ -951,13 +950,13 @@ list_directives() *vim.treesitter.query.list_directives()*
Lists the currently available directives to use in queries.
Return: ~
string[] List of supported directives.
(`string[]`) List of supported directives.
list_predicates() *vim.treesitter.query.list_predicates()*
Lists the currently available predicates to use in queries.
Return: ~
string[] List of supported predicates.
(`string[]`) List of supported predicates.
omnifunc({findstart}, {base}) *vim.treesitter.query.omnifunc()*
Omnifunc for completing node names and predicates in treesitter queries.
@ -980,11 +979,11 @@ parse({lang}, {query}) *vim.treesitter.query.parse()*
• `info.patterns` contains information about predicates.
Parameters: ~
• {lang} (string) Language to use for the query
• {query} (string) Query in s-expr syntax
• {lang} (`string`) Language to use for the query
• {query} (`string`) Query in s-expr syntax
Return: ~
Query Parsed query
(`Query`) Parsed query
*Query:iter_captures()*
Query:iter_captures({node}, {source}, {start}, {stop})
@ -1010,14 +1009,14 @@ Query:iter_captures({node}, {source}, {start}, {stop})
<
Parameters: ~
• {node} |TSNode| under which the search will occur
• {source} (integer|string) Source buffer or string to extract text
• {node} (`TSNode`) under which the search will occur
• {source} (`integer|string`) Source buffer or string to extract text
from
• {start} (integer) Starting line for the search
• {stop} (integer) Stopping line for the search (end-exclusive)
• {start} (`integer`) Starting line for the search
• {stop} (`integer`) Stopping line for the search (end-exclusive)
Return: ~
(fun(end_line: integer|nil): integer, TSNode, TSMetadata): capture id,
(`fun(end_line: integer?): integer, TSNode, TSMetadata`) capture id,
capture node, metadata
*Query:iter_matches()*
@ -1044,18 +1043,18 @@ Query:iter_matches({node}, {source}, {start}, {stop}, {opts})
<
Parameters: ~
• {node} |TSNode| under which the search will occur
• {source} (integer|string) Source buffer or string to search
• {start} (integer) Starting line for the search
• {stop} (integer) Stopping line for the search (end-exclusive)
• {opts} (table|nil) Options:
• {node} (`TSNode`) under which the search will occur
• {source} (`integer|string`) Source buffer or string to search
• {start} (`integer`) Starting line for the search
• {stop} (`integer`) Stopping line for the search (end-exclusive)
• {opts} (`table?`) Options:
• max_start_depth (integer) if non-zero, sets the maximum
start depth for each match. This is used to prevent
traversing too deep into a tree. Requires treesitter >=
0.20.9.
Return: ~
(fun(): integer, table<integer,TSNode>, table): pattern id, match,
(`fun(): integer, table<integer,TSNode>, table`) pattern id, match,
metadata
set({lang}, {query_name}, {text}) *vim.treesitter.query.set()*
@ -1065,9 +1064,9 @@ set({lang}, {query_name}, {text}) *vim.treesitter.query.set()*
by plugins.
Parameters: ~
• {lang} (string) Language to use for the query
• {query_name} (string) Name of the query (e.g., "highlights")
• {text} (string) Query text (unparsed).
• {lang} (`string`) Language to use for the query
• {query_name} (`string`) Name of the query (e.g., "highlights")
• {text} (`string`) Query text (unparsed).
==============================================================================
@ -1117,10 +1116,10 @@ LanguageTree:contains({range}) *LanguageTree:contains()*
Determines whether {range} is contained in the |LanguageTree|.
Parameters: ~
• {range} (table) `{ start_line, start_col, end_line, end_col }`
• {range} (`Range4`) `{ start_line, start_col, end_line, end_col }`
Return: ~
(boolean)
(`boolean`)
LanguageTree:destroy() *LanguageTree:destroy()*
Destroys this |LanguageTree| and all its children.
@ -1136,21 +1135,21 @@ LanguageTree:for_each_tree({fn}) *LanguageTree:for_each_tree()*
Note: This includes the invoking tree's child trees as well.
Parameters: ~
• {fn} fun(tree: TSTree, ltree: LanguageTree)
• {fn} (`fun(tree: TSTree, ltree: LanguageTree)`)
LanguageTree:included_regions() *LanguageTree:included_regions()*
Gets the set of included regions managed by this LanguageTree . This can
be different from the regions set by injection query, because a partial
Gets the set of included regions managed by this LanguageTree . This can be
different from the regions set by injection query, because a partial
|LanguageTree:parse()| drops the regions outside the requested range.
Return: ~
table<integer, Range6[]>
(`table<integer, Range6[]>`)
LanguageTree:invalidate({reload}) *LanguageTree:invalidate()*
Invalidates this parser and all its children
Parameters: ~
• {reload} (boolean|nil)
• {reload} (`boolean?`)
LanguageTree:is_valid({exclude_children}) *LanguageTree:is_valid()*
Returns whether this LanguageTree is valid, i.e., |LanguageTree:trees()|
@ -1158,11 +1157,11 @@ LanguageTree:is_valid({exclude_children}) *LanguageTree:is_valid()*
|LanguageTree:parse()|.
Parameters: ~
• {exclude_children} (boolean|nil) whether to ignore the validity of
• {exclude_children} (`boolean?`) whether to ignore the validity of
children (default `false`)
Return: ~
(boolean)
(`boolean`)
LanguageTree:lang() *LanguageTree:lang()*
Gets the language of this tree node.
@ -1172,23 +1171,23 @@ LanguageTree:language_for_range({range})
Gets the appropriate language that contains {range}.
Parameters: ~
• {range} (table) `{ start_line, start_col, end_line, end_col }`
• {range} (`Range4`) `{ start_line, start_col, end_line, end_col }`
Return: ~
|LanguageTree| Managing {range}
(`LanguageTree`) Managing {range}
*LanguageTree:named_node_for_range()*
LanguageTree:named_node_for_range({range}, {opts})
Gets the smallest named node that contains {range}.
Parameters: ~
• {range} (table) `{ start_line, start_col, end_line, end_col }`
• {opts} (table|nil) Optional keyword arguments:
• {range} (`Range4`) `{ start_line, start_col, end_line, end_col }`
• {opts} (`table?`) Optional keyword arguments:
• ignore_injections boolean Ignore injected languages
(default true)
Return: ~
|TSNode| | nil Found node
(`TSNode?`) Found node
LanguageTree:parse({range}) *LanguageTree:parse()*
Recursively parse all regions in the language tree using
@ -1201,21 +1200,21 @@ LanguageTree:parse({range}) *LanguageTree:parse()*
if {range} is `true`).
Parameters: ~
• {range} boolean|Range|nil: Parse this range in the parser's source.
• {range} (`boolean|Range?`) Parse this range in the parser's source.
Set to `true` to run a complete parse of the source (Note:
Can be slow!) Set to `false|nil` to only parse regions with
empty ranges (typically only the root tree without
injections).
Return: ~
table<integer, TSTree>
(`table<integer, TSTree>`)
*LanguageTree:register_cbs()*
LanguageTree:register_cbs({cbs}, {recursive})
Registers callbacks for the |LanguageTree|.
Parameters: ~
• {cbs} (table) An |nvim_buf_attach()|-like table argument with
• {cbs} (`table`) An |nvim_buf_attach()|-like table argument with
the following handlers:
• `on_bytes` : see |nvim_buf_attach()|, but this will be
called after the parsers callback.
@ -1230,7 +1229,7 @@ LanguageTree:register_cbs({cbs}, {recursive})
• `on_detach` : emitted when the buffer is detached, see
|nvim_buf_detach_event|. Takes one argument, the number
of the buffer.
• {recursive} (boolean|nil) Apply callbacks recursively for all
• {recursive} (`boolean?`) Apply callbacks recursively for all
children. Any new children will also inherit the
callbacks.
@ -1242,13 +1241,13 @@ LanguageTree:tree_for_range({range}, {opts})
Gets the tree that contains {range}.
Parameters: ~
• {range} (table) `{ start_line, start_col, end_line, end_col }`
• {opts} (table|nil) Optional keyword arguments:
• {range} (`Range4`) `{ start_line, start_col, end_line, end_col }`
• {opts} (`table?`) Optional keyword arguments:
• ignore_injections boolean Ignore injected languages
(default true)
Return: ~
TSTree|nil
(`TSTree?`)
LanguageTree:trees() *LanguageTree:trees()*
Returns all trees of the regions parsed by this parser. Does not include
@ -1258,6 +1257,6 @@ LanguageTree:trees() *LanguageTree:trees()*
• the root LanguageTree is fully parsed.
Return: ~
table<integer, TSTree>
(`table<integer, TSTree>`)
vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:

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

@ -95,7 +95,7 @@ vim.log = {
--- throws an error if {cmd} cannot be run.
---
--- @param cmd (string[]) Command to execute
--- @param opts (SystemOpts|nil) Options:
--- @param opts vim.SystemOpts? Options:
--- - cwd: (string) Set the current working directory for the sub-process.
--- - env: table<string,string> Set environment variables for the new process. Inherits the
--- current environment with `NVIM` set to |v:servername|.
@ -118,7 +118,7 @@ vim.log = {
--- parent exits. Note that the child process will still keep the parent's event loop alive
--- unless the parent process calls |uv.unref()| on the child's process handle.
---
--- @param on_exit (function|nil) Called when subprocess exits. When provided, the command runs
--- @param on_exit? fun(out: vim.SystemCompleted) Called when subprocess exits. When provided, the command runs
--- asynchronously. Receives SystemCompleted object, see return of SystemObj:wait().
---
--- @return vim.SystemObj Object with the fields:
@ -219,10 +219,9 @@ do
--- ```
---
---@see |paste|
---@alias paste_phase -1 | 1 | 2 | 3
---
---@param lines string[] # |readfile()|-style list of lines to paste. |channel-lines|
---@param phase paste_phase -1: "non-streaming" paste: the call contains all lines.
---@param phase (-1|1|2|3) -1: "non-streaming" paste: the call contains all lines.
--- If paste is "streamed", `phase` indicates the stream state:
--- - 1: starts the paste (exactly once)
--- - 2: continues the paste (zero or more times)

5
runtime/lua/vim/_meta/api.lua generated
View File

@ -812,9 +812,8 @@ function vim.api.nvim_complete_set(index, opts) end
--- @return integer
function vim.api.nvim_create_augroup(name, opts) end
--- Creates an `autocommand` event handler, defined by `callback` (Lua
--- function or Vimscript function name string) or `command` (Ex command
--- string).
--- Creates an `autocommand` event handler, defined by `callback` (Lua function
--- or Vimscript function name string) or `command` (Ex command string).
--- Example using Lua callback:
---
--- ```lua

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

@ -1,6 +1,6 @@
local uv = vim.uv
--- @class SystemOpts
--- @class vim.SystemOpts
--- @field stdin? string|string[]|true
--- @field stdout? fun(err:string?, data: string?)|false
--- @field stderr? fun(err:string?, data: string?)|false
@ -302,7 +302,7 @@ end
--- Run a system command
---
--- @param cmd string[]
--- @param opts? SystemOpts
--- @param opts? vim.SystemOpts
--- @param on_exit? fun(out: vim.SystemCompleted)
--- @return vim.SystemObj
function M.run(cmd, opts, on_exit)

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

@ -2165,7 +2165,7 @@ end
--- }
--- ```
---
---@param filetypes vim.filetype.add.filetypes A table containing new filetype maps (see example).
---@param filetypes vim.filetype.add.filetypes (table) A table containing new filetype maps (see example).
function M.add(filetypes)
for k, v in pairs(filetypes.extension or {}) do
extension[k] = v
@ -2300,7 +2300,7 @@ end
--- vim.filetype.match({ contents = {'#!/usr/bin/env bash'} })
--- ```
---
---@param args vim.filetype.match.args Table specifying which matching strategy to use.
---@param args vim.filetype.match.args (table) Table specifying which matching strategy to use.
--- Accepted keys are:
--- * buf (number): Buffer number to use for matching. Mutually exclusive with
--- {contents}

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

@ -315,7 +315,7 @@ end
--- Run a system command and timeout after 30 seconds.
---
--- @param cmd table List of command arguments to execute
--- @param args ?table Optional arguments:
--- @param args? table Optional arguments:
--- - stdin (string): Data to write to the job's stdin
--- - stderr (boolean): Append stderr to stdout
--- - ignore_error (boolean): If true, ignore error output

48
runtime/lua/vim/iter.lua
View File

@ -181,9 +181,9 @@ end
--- local bufs = vim.iter(vim.api.nvim_list_bufs()):filter(vim.api.nvim_buf_is_loaded)
--- ```
---
---@param f function(...):bool Takes all values returned from the previous stage
--- in the pipeline and returns false or nil if the
--- current iterator element should be removed.
---@param f fun(...):bool Takes all values returned from the previous stage
--- in the pipeline and returns false or nil if the
--- current iterator element should be removed.
---@return Iter
function Iter.filter(self, f)
return self:map(function(...)
@ -272,11 +272,11 @@ end
--- -- { 6, 12 }
--- ```
---
---@param f function(...):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
--- in the next pipeline stage. Nil return values
--- are filtered from the output.
---@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
--- in the next pipeline stage. Nil return values
--- are filtered from the output.
---@return Iter
function Iter.map(self, f)
-- Implementation note: the reader may be forgiven for observing that this
@ -340,9 +340,9 @@ end
---
--- For functions with side effects. To modify the values in the iterator, use |Iter:map()|.
---
---@param f function(...) Function to execute for each item in the pipeline.
--- Takes all of the values returned by the previous stage
--- in the pipeline as arguments.
---@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.
function Iter.each(self, f)
local function fn(...)
if select(1, ...) ~= nil then
@ -464,7 +464,7 @@ end
---@generic A
---
---@param init A Initial value of the accumulator.
---@param f function(acc:A, ...):A Accumulation function.
---@param f fun(acc:A, ...):A Accumulation function.
---@return A
function Iter.fold(self, init, f)
local acc = init
@ -884,9 +884,9 @@ end
--- Returns true if any of the items in the iterator match the given predicate.
---
---@param pred function(...):bool Predicate function. Takes all values returned from the previous
--- stage in the pipeline as arguments and returns true if the
--- predicate matches.
---@param pred fun(...):bool Predicate function. Takes all values returned from the previous
--- stage in the pipeline as arguments and returns true if the
--- predicate matches.
function Iter.any(self, pred)
local any = false
@ -908,9 +908,9 @@ end
--- Returns true if all items in the iterator match the given predicate.
---
---@param pred function(...):bool Predicate function. Takes all values returned from the previous
--- stage in the pipeline as arguments and returns true if the
--- predicate matches.
---@param pred fun(...):bool Predicate function. Takes all values returned from the previous
--- stage in the pipeline as arguments and returns true if the
--- predicate matches.
function Iter.all(self, pred)
local all = true
@ -1106,9 +1106,9 @@ end
---
---@see |Iter:filter()|
---
---@param f function(...):bool Filter function. Accepts the current iterator or table values as
--- arguments and returns true if those values should be kept in the
--- final table
---@param f fun(...):bool Filter function. Accepts the current iterator or table values as
--- arguments and returns true if those values should be kept in the
--- final table
---@param src table|function Table or iterator function to filter
---@return table
function M.filter(f, src, ...)
@ -1124,9 +1124,9 @@ end
---
---@see |Iter:map()|
---
---@param f function(...):?any Map function. Accepts the current iterator or table values as
--- arguments and returns one or more new values. Nil values are removed
--- from the final table.
---@param f fun(...): any? Map function. Accepts the current iterator or table values as
--- arguments and returns one or more new values. Nil values are removed
--- from the final table.
---@param src table|function Table or iterator function to filter
---@return table
function M.map(f, src, ...)

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

@ -516,7 +516,7 @@ end
---
--- Displays call hierarchy in the quickfix window.
---
---@param direction `"from"` for incoming calls and `"to"` for outgoing calls
---@param direction 'from'|'to' `"from"` for incoming calls and `"to"` for outgoing calls
---@return function
--- `CallHierarchyIncomingCall[]` if {direction} is `"from"`,
--- `CallHierarchyOutgoingCall[]` if {direction} is `"to"`,

6
runtime/lua/vim/lsp/util.lua
View File

@ -790,7 +790,7 @@ end
--- Note that if the input is of type `MarkupContent` and its kind is `plaintext`,
--- then the corresponding value is returned without further modifications.
---
---@param input (`MarkedString` | `MarkedString[]` | `MarkupContent`)
---@param input (lsp.MarkedString | lsp.MarkedString[] | lsp.MarkupContent)
---@param contents (table|nil) List of strings to extend with converted lines. Defaults to {}.
---@return string[] extended with lines of converted markdown.
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
@ -2115,8 +2115,8 @@ end
--- Returns the UTF-32 and UTF-16 offsets for a position in a certain buffer.
---
---@param buf integer buffer number (0 for current)
---@param row 0-indexed line
---@param col 0-indexed byte offset in line
---@param row integer 0-indexed line
---@param col integer 0-indexed byte offset in line
---@param offset_encoding string utf-8|utf-16|utf-32 defaults to `offset_encoding` of first client of `buf`
---@return integer `offset_encoding` index of the character in line {row} column {col} in buffer {buf}
function M.character_offset(buf, row, col, offset_encoding)

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

@ -875,7 +875,7 @@ end
--- a.b.c = 1
--- ```
---
---@param createfn function?(key:any):any Provides the value for a missing `key`.
---@param createfn? fun(key:any):any Provides the value for a missing `key`.
---@return table # Empty table with `__index` metamethod.
function vim.defaulttable(createfn)
createfn = createfn or function(_)

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

@ -793,7 +793,7 @@ end
--- of the query file, e.g., if the path ends in `/lua/highlights.scm`, the parser for the
--- `lua` language will be used.
---@param buf (integer) Buffer handle
---@param opts (QueryLinterOpts|nil) Optional keyword arguments:
---@param opts? QueryLinterOpts (table) Optional keyword arguments:
--- - langs (string|string[]|nil) Language(s) to use for checking the query.
--- If multiple languages are specified, queries are validated for all of them
--- - clear (boolean) if `true`, just clear current lint errors

14
scripts/gen_vimdoc.py
View File

@ -717,12 +717,14 @@ def render_node(n: Element, text: str, prefix='', *,
elif n.nodeName in ('para', 'heading'):
did_prefix = False
for c in n.childNodes:
c_text = render_node(c, text, prefix=(prefix if not did_prefix else ''), indent=indent, width=width)
if (is_inline(c)
and '' != get_text(c).strip()
and '' != c_text.strip()
and text
and ' ' != text[-1]):
and text[-1] not in (' ', '(', '|')
and not c_text.startswith(')')):
text += ' '
text += render_node(c, text, prefix=(prefix if not did_prefix else ''), indent=indent, width=width)
text += c_text
did_prefix = True
elif n.nodeName == 'itemizedlist':
for c in n.childNodes:
@ -840,15 +842,17 @@ def para_as_map(parent: Element,
raise RuntimeError('unhandled simplesect: {}\n{}'.format(
child.nodeName, child.toprettyxml(indent=' ', newl='\n')))
else:
child_text = render_node(child, text, indent=indent, width=width)
if (prev is not None
and is_inline(self_or_child(prev))
and is_inline(self_or_child(child))
and '' != get_text(self_or_child(child)).strip()
and text
and ' ' != text[-1]):
and text[-1] not in (' ', '(', '|')
and not child_text.startswith(')')):
text += ' '
text += render_node(child, text, indent=indent, width=width)
text += child_text
prev = child
chunks['text'] += text

202
scripts/lua2dox.lua
View File

@ -55,17 +55,7 @@ The effect is that you will get the function documented, but not with the parame
local TYPES = { 'integer', 'number', 'string', 'table', 'list', 'boolean', 'function' }
local TAGGED_TYPES = { 'TSNode', 'LanguageTree' }
-- Document these as 'table'
local ALIAS_TYPES = {
'Range',
'Range4',
'Range6',
'TSMetadata',
'vim.filetype.add.filetypes',
'vim.filetype.match.args',
}
local luacats_parser = require('src/nvim/generators/luacats_grammar')
local debug_outfile = nil --- @type string?
local debug_output = {}
@ -161,6 +151,91 @@ local function removeCommentFromLine(line)
return line:sub(1, pos_comment - 1), line:sub(pos_comment)
end
--- @param parsed luacats.Return
--- @return string
local function get_return_type(parsed)
local elems = {} --- @type string[]
for _, v in ipairs(parsed) do
local e = v.type --- @type string
if v.name then
e = e .. ' ' .. v.name --- @type string
end
elems[#elems + 1] = e
end
return '(' .. table.concat(elems, ', ') .. ')'
end
--- @param name string
--- @return string
local function process_name(name, optional)
if optional then
name = name:sub(1, -2) --- @type string
end
return name
end
--- @param ty string
--- @param generics table<string,string>
--- @return string
local function process_type(ty, generics, optional)
-- replace generic types
for k, v in pairs(generics) do
ty = ty:gsub(k, v) --- @type string
end
-- strip parens
ty = ty:gsub('^%((.*)%)$', '%1')
if optional and not ty:find('nil') then
ty = ty .. '?'
end
-- remove whitespace in unions
ty = ty:gsub('%s*|%s*', '|')
-- replace '|nil' with '?'
ty = ty:gsub('|nil', '?')
ty = ty:gsub('nil|(.*)', '%1?')
return '(`' .. ty .. '`)'
end
--- @param parsed luacats.Param
--- @param generics table<string,string>
--- @return string
local function process_param(parsed, generics)
local name, ty = parsed.name, parsed.type
local optional = vim.endswith(name, '?')
return table.concat({
'/// @param',
process_name(name, optional),
process_type(ty, generics, optional),
parsed.desc,
}, ' ')
end
--- @param parsed luacats.Return
--- @param generics table<string,string>
--- @return string
local function process_return(parsed, generics)
local ty, name --- @type string, string
if #parsed == 1 then
ty, name = parsed[1].type, parsed[1].name or ''
else
ty, name = get_return_type(parsed), ''
end
local optional = vim.endswith(name, '?')
return table.concat({
'/// @return',
process_type(ty, generics, optional),
process_name(name, optional),
parsed.desc,
}, ' ')
end
--- Processes "@…" directives in a docstring line.
---
--- @param line string
@ -175,93 +250,54 @@ local function process_magic(line, generics)
return '/// ' .. line
end
local magic = line:sub(2)
local magic_split = vim.split(magic, ' ', { plain = true })
local magic_split = vim.split(line, ' ', { plain = true })
local directive = magic_split[1]
if
vim.list_contains({
'cast',
'diagnostic',
'overload',
'meta',
'type',
'@cast',
'@diagnostic',
'@overload',
'@meta',
'@type',
}, directive)
then
-- Ignore LSP directives
return '// gg:"' .. line .. '"'
end
if directive == 'defgroup' or directive == 'addtogroup' then
elseif directive == '@defgroup' or directive == '@addtogroup' then
-- Can't use '.' in defgroup, so convert to '--'
return '/// @' .. magic:gsub('%.', '-dot-')
return '/// ' .. line:gsub('%.', '-dot-')
end
if directive == 'generic' then
local generic_name, generic_type = line:match('@generic%s*(%w+)%s*:?%s*(.*)')
if generic_type == '' then
generic_type = 'any'
-- preprocess line before parsing
if directive == '@param' or directive == '@return' then
for _, type in ipairs(TYPES) do
line = line:gsub('^@param%s+([a-zA-Z_?]+)%s+.*%((' .. type .. ')%)', '@param %1 %2')
line = line:gsub('^@param%s+([a-zA-Z_?]+)%s+.*%((' .. type .. '|nil)%)', '@param %1 %2')
line = line:gsub('^@return%s+.*%((' .. type .. ')%)', '@return %1')
line = line:gsub('^@return%s+.*%((' .. type .. '|nil)%)', '@return %1')
end
generics[generic_name] = generic_type
end
local parsed = luacats_parser:match(line)
if not parsed then
return '/// ' .. line
end
local kind = parsed.kind
if kind == 'generic' then
generics[parsed.name] = parsed.type or 'any'
return
elseif kind == 'param' then
return process_param(parsed --[[@as luacats.Param]], generics)
elseif kind == 'return' then
return process_return(parsed --[[@as luacats.Return]], generics)
end
local type_index = 2
if directive == 'param' then
for _, type in ipairs(TYPES) do
magic = magic:gsub('^param%s+([a-zA-Z_?]+)%s+.*%((' .. type .. ')%)', 'param %1 %2')
magic = magic:gsub('^param%s+([a-zA-Z_?]+)%s+.*%((' .. type .. '|nil)%)', 'param %1 %2')
end
magic_split = vim.split(magic, ' ', { plain = true })
type_index = 3
elseif directive == 'return' then
for _, type in ipairs(TYPES) do
magic = magic:gsub('^return%s+.*%((' .. type .. ')%)', 'return %1')
magic = magic:gsub('^return%s+.*%((' .. type .. '|nil)%)', 'return %1')
end
-- Remove first "#" comment char, if any. https://github.com/LuaLS/lua-language-server/wiki/Annotations#return
magic = magic:gsub('# ', '', 1)
-- handle the return of vim.spell.check
magic = magic:gsub('({.*}%[%])', '`%1`')
magic_split = vim.split(magic, ' ', { plain = true })
end
local ty = magic_split[type_index]
if ty then
-- fix optional parameters
if magic_split[2]:find('%?$') then
if not ty:find('nil') then
ty = ty .. '|nil'
end
magic_split[2] = magic_split[2]:sub(1, -2)
end
-- replace generic types
for k, v in pairs(generics) do
ty = ty:gsub(k, v) --- @type string
end
for _, type in ipairs(TAGGED_TYPES) do
ty = ty:gsub(type, '|%1|')
end
for _, type in ipairs(ALIAS_TYPES) do
ty = ty:gsub('^' .. type .. '$', 'table') --- @type string
end
-- surround some types by ()
for _, type in ipairs(TYPES) do
ty = ty:gsub('^(' .. type .. '|nil):?$', '(%1)'):gsub('^(' .. type .. '):?$', '(%1)')
end
magic_split[type_index] = ty
end
magic = table.concat(magic_split, ' ')
return '/// @' .. magic
error(string.format('unhandled parsed line %q: %s', line, parsed))
end
--- @param line string

2
src/nvim/CMakeLists.txt
View File

@ -925,6 +925,8 @@ add_custom_command(
${API_SOURCES}
${LUA_SOURCES}
${VIMDOC_FILES}
${PROJECT_SOURCE_DIR}/scripts/gen_vimdoc.py
${PROJECT_SOURCE_DIR}/scripts/lua2dox.lua
WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
)

136
src/nvim/generators/luacats_grammar.lua Normal file
View File

@ -0,0 +1,136 @@
--[[!
LPEG grammar for LuaCATS
Currently only partially supports:
- @param
- @return
]]
local lpeg = vim.lpeg
local P, R, S = lpeg.P, lpeg.R, lpeg.S
local Ct, Cg = lpeg.Ct, lpeg.Cg
--- @param x vim.lpeg.Pattern
local function rep(x)
return x ^ 0
end
--- @param x vim.lpeg.Pattern
local function rep1(x)
return x ^ 1
end
--- @param x vim.lpeg.Pattern
local function opt(x)
return x ^ -1
end
local nl = P('\r\n') + P('\n')
local ws = rep1(S(' \t') + nl)
local fill = opt(ws)
local any = P(1) -- (consume one character)
local letter = R('az', 'AZ') + S('_$')
local num = R('09')
local ident = letter * rep(letter + num + S '-.')
local string_single = P "'" * rep(any - P "'") * P "'"
local string_double = P '"' * rep(any - P '"') * P '"'
local literal = (string_single + string_double + (opt(P '-') * num) + P 'false' + P 'true')
local lname = (ident + P '...') * opt(P '?')
--- @param x string
local function Pf(x)
return fill * P(x) * fill
end
--- @param x string
local function Sf(x)
return fill * S(x) * fill
end
--- @param x vim.lpeg.Pattern
local function comma(x)
return x * rep(Pf ',' * x)
end
--- @param x vim.lpeg.Pattern
local function parenOpt(x)
return (Pf('(') * x ^ -1 * fill * P(')')) + x ^ -1
end
--- @type table<string,vim.lpeg.Pattern>
local v = setmetatable({}, {
__index = function(_, k)
return lpeg.V(k)
end,
})
local desc_delim = Sf '#:' + ws
--- @class luacats.Param
--- @field kind 'param'
--- @field name string
--- @field type string
--- @field desc? string
--- @class luacats.Return
--- @field kind 'return'
--- @field [integer] { type: string, name?: string}
--- @field desc? string
--- @class luacats.Generic
--- @field kind 'generic'
--- @field name string
--- @field type? string
--- @alias luacats.grammar.result
--- | luacats.Param
--- | luacats.Return
--- | luacats.Generic
--- @class luacats.grammar
--- @field match fun(self, input: string): luacats.grammar.result?
local grammar = P {
rep1(P('@') * v.ats),
ats = (v.at_param + v.at_return + v.at_generic),
at_param = Ct(
Cg(P('param'), 'kind')
* ws
* Cg(lname, 'name')
* ws
* Cg(v.ltype, 'type')
* opt(desc_delim * Cg(rep(any), 'desc'))
),
at_return = Ct(
Cg(P('return'), 'kind')
* ws
* parenOpt(comma(Ct(Cg(v.ltype, 'type') * opt(ws * Cg(ident, 'name')))))
* opt(desc_delim * Cg(rep(any), 'desc'))
),
at_generic = Ct(
Cg(P('generic'), 'kind') * ws * Cg(ident, 'name') * opt(Pf ':' * Cg(v.ltype, 'type'))
),
ltype = v.ty_union + Pf '(' * v.ty_union * fill * P ')',
ty_union = v.ty_opt * rep(Pf '|' * v.ty_opt),
ty = v.ty_fun + ident + v.ty_table + literal,
ty_param = Pf '<' * comma(v.ltype) * fill * P '>',
ty_opt = v.ty * opt(v.ty_param) * opt(P '[]') * opt(P '?'),
table_key = (Pf '[' * literal * Pf ']') + lname,
table_elem = v.table_key * Pf ':' * v.ltype,
ty_table = Pf '{' * comma(v.table_elem) * Pf '}',
fun_param = lname * opt(Pf ':' * v.ltype),
ty_fun = Pf 'fun(' * rep(comma(v.fun_param)) * fill * P ')' * opt(Pf ':' * v.ltype),
}
return grammar --[[@as luacats.grammar]]

133
test/functional/luacats_grammar_spec.lua Normal file
View File

@ -0,0 +1,133 @@
local helpers = require('test.functional.helpers')(after_each)
local eq = helpers.eq
local grammar = require('src/nvim/generators/luacats_grammar')
describe('luacats grammar', function()
--- @param text string
--- @param exp table<string,string>
local function test(text, exp)
it(string.format('can parse %q', text), function()
eq(exp, grammar:match(text))
end)
end
test('@param hello vim.type', {
kind = 'param',
name = 'hello',
type = 'vim.type',
})
test('@param hello vim.type this is a description', {
kind = 'param',
name = 'hello',
type = 'vim.type',
desc = 'this is a description',
})
test('@param hello vim.type|string this is a description', {
kind = 'param',
name = 'hello',
type = 'vim.type|string',
desc = 'this is a description',
})
test('@param hello vim.type?|string? this is a description', {
kind = 'param',
name = 'hello',
type = 'vim.type?|string?',
desc = 'this is a description',
})
test('@return string hello this is a description', {
kind = 'return',
{
name = 'hello',
type = 'string',
},
desc = 'this is a description',
})
test('@return fun() hello this is a description', {
kind = 'return',
{
name = 'hello',
type = 'fun()',
},
desc = 'this is a description',
})
test('@return fun(a: string[]): string hello this is a description', {
kind = 'return',
{
name = 'hello',
type = 'fun(a: string[]): string',
},
desc = 'this is a description',
})
test('@return fun(a: table<string,any>): string hello this is a description', {
kind = 'return',
{
name = 'hello',
type = 'fun(a: table<string,any>): string',
},
desc = 'this is a description',
})
test('@param ... string desc', {
kind = 'param',
name = '...',
type = 'string',
desc = 'desc',
})
test('@param level (integer|string) desc', {
kind = 'param',
name = 'level',
type = '(integer|string)',
desc = 'desc',
})
test('@return (string command) the command and arguments', {
kind = 'return',
{
name = 'command',
type = 'string',
},
desc = 'the command and arguments',
})
test('@return (string command, string[] args) the command and arguments', {
kind = 'return',
{
name = 'command',
type = 'string',
},
{
name = 'args',
type = 'string[]',
},
desc = 'the command and arguments',
})
test('@param rfc "rfc2396" | "rfc2732" | "rfc3986" | nil', {
kind = 'param',
name = 'rfc',
type = '"rfc2396" | "rfc2732" | "rfc3986" | nil',
})
test('@param offset_encoding "utf-8" | "utf-16" | "utf-32" | nil', {
kind = 'param',
name = 'offset_encoding',
type = '"utf-8" | "utf-16" | "utf-32" | nil',
})
-- handle a : after the param type
test('@param a b: desc', {
kind = 'param',
name = 'a',
type = 'b',
desc = 'desc',
})
end)