diff options
| author | Lewis Russell <lewis6991@gmail.com> | 2024-03-08 12:25:18 +0000 |
|---|---|---|
| committer | Lewis Russell <me@lewisr.dev> | 2024-03-09 11:21:55 +0000 |
| commit | ade1b12f49c3b3914c74847d791eb90ea90b56b7 (patch) | |
| tree | b76b5f4cbb3398c7c7081e33db0b8fba99600f6e | |
| parent | 0e284939143ae5bd55f78ece388346811af842ea (diff) | |
| download | rneovim-ade1b12f49c3b3914c74847d791eb90ea90b56b7.tar.gz rneovim-ade1b12f49c3b3914c74847d791eb90ea90b56b7.tar.bz2 rneovim-ade1b12f49c3b3914c74847d791eb90ea90b56b7.zip | |
docs: support inline markdown
- Tags are now created with `[tag]()`
- References are now created with `[tag]`
- Code spans are no longer wrapped
28 files changed, 414 insertions, 250 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 1b00777532..87269ad147 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -770,9 +770,9 @@ nvim_echo({chunks}, {history}, {opts}) *nvim_echo()* Echo a message. Parameters: ~ - • {chunks} A list of [text, hl_group] arrays, each representing a text - chunk with specified highlight. `hl_group` element can be - omitted for no highlight. + • {chunks} A list of `[text, hl_group]` arrays, each representing a + text chunk with specified highlight. `hl_group` element can + be omitted for no highlight. • {history} if true, add to |message-history|. • {opts} Optional parameters. • verbose: Message was printed as a result of 'verbose' @@ -883,7 +883,7 @@ nvim_get_api_info() *nvim_get_api_info()* |RPC| only Return: ~ - 2-tuple [{channel-id}, {api-metadata}] + 2-tuple `[{channel-id}, {api-metadata}]` nvim_get_chan_info({chan}) *nvim_get_chan_info()* Gets information about a channel. @@ -1115,7 +1115,7 @@ nvim_input({keys}) *nvim_input()* • |keycodes| like <CR> are translated, so "<" is special. To input a literal "<", send <LT>. • For mouse events use |nvim_input_mouse()|. The pseudokey form - "<LeftMouse><col,row>" is deprecated since |api-level| 6. + `<LeftMouse><col,row>` is deprecated since |api-level| 6. Attributes: ~ |api-fast| @@ -1138,7 +1138,7 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col}) • Currently this doesn't support "scripting" multiple mouse events by calling it multiple times in a loop: the intermediate mouse positions will be ignored. It should be used to implement real-time mouse input - in a GUI. The deprecated pseudokey form ("<LeftMouse><col,row>") of + in a GUI. The deprecated pseudokey form (`<LeftMouse><col,row>`) of |nvim_input()| has the same limitation. Attributes: ~ @@ -1246,7 +1246,7 @@ nvim_open_term({buffer}, {opts}) *nvim_open_term()* be to the pty master end. For instance, a carriage return is sent as a "\r", not as a "\n". |textlock| applies. It is possible to call |nvim_chan_send()| directly in the - callback however. ["input", term, bufnr, data] + callback however. `["input", term, bufnr, data]` • force_crlf: (boolean, default true) Convert "\n" to "\r\n". @@ -1523,7 +1523,7 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {opts}) *nvim_set_keymap()* To set a buffer-local mapping, use |nvim_buf_set_keymap()|. Unlike |:map|, leading/trailing whitespace is accepted as part of the - {lhs} or {rhs}. Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual. + {lhs} or {rhs}. Empty {rhs} is <Nop>. |keycodes| are replaced as usual. Example: >vim call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true}) @@ -1541,7 +1541,7 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {opts}) *nvim_set_keymap()* • {lhs} Left-hand-side |{lhs}| of the mapping. • {rhs} Right-hand-side |{rhs}| of the mapping. • {opts} Optional parameters map: Accepts all |:map-arguments| as keys - except |<buffer>|, values are booleans (default false). Also: + except <buffer>, values are booleans (default false). Also: • "noremap" disables |recursive_mapping|, like |:noremap| • "desc" human-readable description. • "callback" Lua function called in place of {rhs}. @@ -1689,8 +1689,8 @@ nvim_parse_expression({expr}, {flags}, {highlight}) operator/space, though also yielding an error). • "l" when needing to start parsing with lvalues for ":let" or ":for". Common flag sets: - • "m" to parse like for ":echo". - • "E" to parse like for "<C-r>=". + • "m" to parse like for `":echo"`. + • "E" to parse like for `"<C-r>="`. • empty string for ":call". • "lm" to parse for ":let". • {highlight} If true, return value will also include "highlight" key @@ -1714,7 +1714,7 @@ nvim_parse_expression({expr}, {flags}, {highlight}) • "ast": AST, either nil or a dictionary with these keys: • "type": node type, one of the value names from ExprASTNodeType stringified without "kExprNode" prefix. - • "start": a pair [line, column] describing where node is + • "start": a pair `[line, column]` describing where node is "started" where "line" is always 0 (will not be 0 if you will be using this API on e.g. ":let", but that is not present yet). Both elements are Integers. @@ -1839,22 +1839,21 @@ nvim_create_user_command({name}, {command}, {opts}) argument that contains the following keys: • name: (string) Command name • args: (string) The args passed to the command, if any - |<args>| + <args> • fargs: (table) The args split by unescaped whitespace - (when more than one argument is allowed), if any - |<f-args>| + (when more than one argument is allowed), if any <f-args> • nargs: (string) Number of arguments |:command-nargs| • bang: (boolean) "true" if the command was executed with a - ! modifier |<bang>| + ! modifier <bang> • line1: (number) The starting line of the command range - |<line1>| + <line1> • line2: (number) The final line of the command range - |<line2>| + <line2> • range: (number) The number of items in the command range: - 0, 1, or 2 |<range>| - • count: (number) Any count supplied |<count>| - • reg: (string) The optional register, if specified |<reg>| - • mods: (string) Command modifiers, if any |<mods>| + 0, 1, or 2 <range> + • count: (number) Any count supplied <count> + • reg: (string) The optional register, if specified <reg> + • mods: (string) Command modifiers, if any <mods> • smods: (table) Command modifiers in a structured format. Has the same structure as the "mods" key of |nvim_parse_cmd()|. @@ -1908,16 +1907,15 @@ nvim_parse_cmd({str}, {opts}) *nvim_parse_cmd()* Return: ~ Dictionary containing command information, with these keys: • cmd: (string) Command name. - • range: (array) (optional) Command range (|<line1>| |<line2>|). - Omitted if command doesn't accept a range. Otherwise, has no - elements if no range was specified, one element if only a single - range item was specified, or two elements if both range items were - specified. - • count: (number) (optional) Command |<count>|. Omitted if command + • range: (array) (optional) Command range (<line1> <line2>). Omitted + if command doesn't accept a range. Otherwise, has no elements if no + range was specified, one element if only a single range item was + specified, or two elements if both range items were specified. + • count: (number) (optional) Command <count>. Omitted if command cannot take a count. - • reg: (string) (optional) Command |<register>|. Omitted if command + • reg: (string) (optional) Command <register>. Omitted if command cannot take a register. - • bang: (boolean) Whether command contains a |<bang>| (!) modifier. + • bang: (boolean) Whether command contains a <bang> (!) modifier. • args: (array) Command arguments. • addr: (string) Value of |:command-addr|. Uses short name or "line" for -addr=lines. @@ -2467,9 +2465,9 @@ nvim_buf_set_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col}, Indexing is zero-based. Row indices are end-inclusive, and column indices are end-exclusive. - To insert text at a given `(row, column)` location, use `start_row = - end_row = row` and `start_col = end_col = col`. To delete the text in a - range, use `replacement = {}`. + To insert text at a given `(row, column)` location, use + `start_row = end_row = row` and `start_col = end_col = col`. To delete the + text in a range, use `replacement = {}`. Prefer |nvim_buf_set_lines()| if you are only adding or deleting entire lines. @@ -2639,7 +2637,7 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) "virt_text" and "virt_lines" Return: ~ - List of [extmark_id, row, col] tuples in "traversal order". + List of `[extmark_id, row, col]` tuples in "traversal order". *nvim_buf_set_extmark()* nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) @@ -2674,7 +2672,7 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) EOL of a line, continue the highlight for the rest of the screen line (just like for diff and cursorline highlight). • virt_text : virtual text to link to this mark. A list of - [text, highlight] tuples, each representing a text chunk + `[text, highlight]` tuples, each representing a text chunk with specified highlight. `highlight` element can either be a single highlight group, or an array of multiple highlight groups that will be stacked (highest priority @@ -2707,13 +2705,14 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) for "inline" virt_text. • virt_lines : virtual lines to add next to this mark This should be an array over lines, where each line in turn is - an array over [text, highlight] tuples. In general, buffer - and window options do not affect the display of the text. - In particular 'wrap' and 'linebreak' options do not take - effect, so the number of extra screen lines will always - match the size of the array. However the 'tabstop' buffer - option is still used for hard tabs. By default lines are - placed below the buffer line containing the mark. + an array over `[text, highlight]` tuples. In general, + buffer and window options do not affect the display of the + text. In particular 'wrap' and 'linebreak' options do not + take effect, so the number of extra screen lines will + always match the size of the array. However the 'tabstop' + buffer option is still used for hard tabs. By default + lines are placed below the buffer line containing the + mark. • virt_lines_above: place virtual lines above instead. • virt_lines_leftcol: Place extmarks in the leftmost column of the window, bypassing sign and number columns. @@ -2833,16 +2832,23 @@ nvim_set_decoration_provider({ns_id}, {opts}) Parameters: ~ • {ns_id} Namespace id from |nvim_create_namespace()| • {opts} Table of callbacks: - • on_start: called first on each screen redraw ["start", - tick] + • on_start: called first on each screen redraw > + ["start", tick] +< • on_buf: called for each buffer being redrawn (before window - callbacks) ["buf", bufnr, tick] - • on_win: called when starting to redraw a specific window. - ["win", winid, bufnr, topline, botline] + callbacks) > + ["buf", bufnr, tick] +< + • on_win: called when starting to redraw a specific window. > + ["win", winid, bufnr, topline, botline] +< • on_line: called for each buffer line being redrawn. (The - interaction with fold lines is subject to change) ["line", - winid, bufnr, row] - • on_end: called at the end of a redraw cycle ["end", tick] + interaction with fold lines is subject to change) > + ["line", winid, bufnr, row] +< + • on_end: called at the end of a redraw cycle > + ["end", tick] +< nvim_win_add_ns({window}, {ns_id}) *nvim_win_add_ns()* Adds the namespace scope to the window. @@ -3181,9 +3187,9 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* • width: Window width (in character cells). Minimum of 1. • height: Window height (in character cells). Minimum of 1. • bufpos: Places float relative to buffer text (only when - relative="win"). Takes a tuple of zero-indexed [line, - column]. `row` and `col` if given are applied relative to - this position, else they default to: + relative="win"). Takes a tuple of zero-indexed + `[line, column]`. `row` and `col` if given are applied + relative to this position, else they default to: • `row=1` and `col=0` if `anchor` is "NW" or "NE" • `row=0` and `col=0` if `anchor` is "SW" or "SE" (thus like a tooltip near the buffer text). @@ -3474,9 +3480,9 @@ nvim_create_autocmd({event}, {opts}) *nvim_create_autocmd()* • event: (string) name of the triggered event |autocmd-events| • group: (number|nil) autocommand group id, if any - • match: (string) expanded value of |<amatch>| - • buf: (number) expanded value of |<abuf>| - • file: (string) expanded value of |<afile>| + • match: (string) expanded value of <amatch> + • buf: (number) expanded value of <abuf> + • file: (string) expanded value of <afile> • data: (any) arbitrary data passed from |nvim_exec_autocmds()| • command (string) optional: Vim command to execute on event. @@ -3542,7 +3548,7 @@ nvim_exec_autocmds({event}, {opts}) *nvim_exec_autocmds()* • buffer (integer) optional: buffer number |autocmd-buflocal|. Cannot be used with {pattern}. • modeline (bool) optional: defaults to true. Process the - modeline after the autocommands |<nomodeline>|. + modeline after the autocommands <nomodeline>. • data (any): arbitrary data to send to the autocommand callback. See |nvim_create_autocmd()| for details. diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 1d566efec8..767f46ad1e 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -184,7 +184,7 @@ Strict "vimdoc" subset: C docstrings ~ -Nvim API documentation lives in the source code, as docstrings (Doxygen +Nvim API documentation lives in the source code, as docstrings (doc comments) on the function definitions. The |api| :help is generated from the docstrings defined in src/nvim/api/*.c. @@ -193,6 +193,8 @@ Docstring format: - Special tokens start with `@` followed by the token name: `@note`, `@param`, `@return` - Markdown is supported. +- Tags are written as `[tag]()`. +- References are written as `[tag]` - Use ``` for code samples. Code samples can be annotated as `vim` or `lua` @@ -235,6 +237,8 @@ definitions. The |lua-vim| :help is generated from the docstrings. Docstring format: - Use LuaCATS annotations: https://luals.github.io/wiki/annotations/ - Markdown is supported. +- Tags are written as `[tag]()`. +- References are written as `[tag]` - Use ``` for code samples. Code samples can be annotated as `vim` or `lua` - Use `@nodoc` to prevent documentation generation. diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt index c61c17c9b0..c9e783ca62 100644 --- a/runtime/doc/diagnostic.txt +++ b/runtime/doc/diagnostic.txt @@ -429,7 +429,7 @@ Lua module: vim.diagnostic *diagnostic-api* • {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 + • {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) @@ -486,8 +486,8 @@ Lua module: vim.diagnostic *diagnostic-api* 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 `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()|. @@ -550,10 +550,9 @@ Lua module: vim.diagnostic *diagnostic-api* 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. + • {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 diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index 9b1f2d67cd..eb37cb2a6f 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -719,10 +719,10 @@ formatexpr({opts}) *vim.lsp.formatexpr()* Provides an interface between the built-in client and a `formatexpr` function. - Currently only supports a single client. This can be set via `setlocal - formatexpr=v:lua.vim.lsp.formatexpr()` but will typically or in - `on_attach` via `vim.bo[bufnr].formatexpr = - 'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})'`. + Currently only supports a single client. This can be set via + `setlocal formatexpr=v:lua.vim.lsp.formatexpr()` but will typically or in + `on_attach` via + `vim.bo[bufnr].formatexpr = 'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})'`. Parameters: ~ • {opts} (`table?`) A table with the following fields: @@ -844,11 +844,11 @@ start({config}, {opts}) *vim.lsp.start()* • {config} (`vim.lsp.ClientConfig`) Configuration for the server. See |vim.lsp.ClientConfig|. • {opts} (`table?`) Optional keyword arguments - • {reuse_client} (`fun(client: vim.lsp.Client, config: - table): boolean`) Predicate used to decide if a client - should be re-used. Used on all running clients. The - default implementation re-uses a client if name and - root_dir matches. + • {reuse_client} + (`fun(client: vim.lsp.Client, config: table): boolean`) + Predicate used to decide if a client should be re-used. + Used on all running clients. The default implementation + re-uses a client if name and root_dir matches. • {bufnr} (`integer`) Buffer handle to attach to if starting or re-using a client (0 for current). @@ -965,12 +965,12 @@ Lua module: vim.lsp.client *lsp-client* folders but none are configured. • {root_dir} (`string`) • {attached_buffers} (`table<integer,true>`) - • {commands} (`table<string,fun(command: lsp.Command, ctx: - table)>`) Table of command name to function - which is called if any LSP action (code - action, code lenses, ...) triggers the - command. Client commands take precedence over - the global command registry. + • {commands} (`table<string,fun(command: lsp.Command, ctx: table)>`) + Table of command name to function which is + called if any LSP action (code action, code + lenses, ...) triggers the command. Client + commands take precedence over the global + command registry. • {settings} (`table`) Map with language server specific settings. These are returned to the language server if requested via @@ -991,8 +991,7 @@ Lua module: vim.lsp.client *lsp-client* 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`) + • {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`) @@ -1002,7 +1001,7 @@ Lua module: vim.lsp.client *lsp-client* additional checking. If {handler} is not specified and if there's no respective global handler, then an error will occur. Returns: - {status}, {[client_id]}. {status} is a boolean + {status}, {client_id}?. {status} is a boolean indicating if the notification was successful. If it is `false`, then it will always be `false` (the client has shutdown). If {status} @@ -1012,9 +1011,9 @@ Lua module: vim.lsp.client *lsp-client* the request. • {request_sync} (`fun(method: string, params: table?, timeout_ms: integer?, bufnr: integer): {err: lsp.ResponseError?, result:any}?, string?`) err # a dictionary, where - • {notify} (`fun(method: string, params: table?): - boolean`) Sends a notification to an LSP - server. Returns: a boolean to indicate if the + • {notify} (`fun(method: string, params: table?): boolean`) + Sends a notification to an LSP server. + Returns: a boolean to indicate if the notification was successful. If it is false, then it will always be false (the client has shutdown). @@ -1033,9 +1032,9 @@ Lua module: vim.lsp.client *lsp-client* • {supports_method} (`fun(method: string, opts?: {bufnr: integer?}): boolean`) Checks if a client supports a given method. Always returns true for unknown off-spec - methods. [opts] is a optional `{bufnr?: - integer}` table. Some language server - capabilities can be file specific. + methods. {opts} is a optional + `{bufnr?: integer}` table. Some language + server capabilities can be file specific. • {is_stopped} (`fun(): boolean`) Checks whether a client is stopped. Returns: true if the client is fully stopped. @@ -1095,22 +1094,21 @@ Lua module: vim.lsp.client *lsp-client* • {settings}? (`table`) Map with language server specific settings. See the {settings} in |vim.lsp.Client|. - • {commands}? (`table<string,fun(command: lsp.Command, ctx: - table)>`) Table that maps string of clientside - commands to user-defined functions. Commands - passed to start_client take precedence over the - global command registry. Each key must be a - unique command name, and the value is a function - which is called if any LSP action (code action, - code lenses, ...) triggers the command. + • {commands}? (`table<string,fun(command: lsp.Command, ctx: table)>`) + Table that maps string of clientside commands to + user-defined functions. Commands passed to + start_client take precedence over the global + command registry. Each key must be a unique + command name, and the value is a function which + is called if any LSP action (code action, code + lenses, ...) triggers the command. • {init_options}? (`table`) Values to pass in the initialization request as `initializationOptions`. See `initialize` in the LSP spec. • {name}? (`string`, default: client-id) Name in log messages. - • {get_language_id}? (`fun(bufnr: integer, filetype: string): - string`) Language ID as string. Defaults to the - filetype. + • {get_language_id}? (`fun(bufnr: integer, filetype: string): string`) + Language ID as string. Defaults to the filetype. • {offset_encoding}? (`'utf-8'|'utf-16'|'utf-32'`) The encoding that the LSP server expects. Client does not verify this is correct. @@ -2222,8 +2220,7 @@ connect({host}, {port}) *vim.lsp.rpc.connect()* • {port} (`integer`) port to connect to Return: ~ - (`fun(dispatchers: vim.lsp.rpc.Dispatchers): - vim.lsp.rpc.PublicClient`) + (`fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`) *vim.lsp.rpc.domain_socket_connect()* domain_socket_connect({pipe_path}) @@ -2239,8 +2236,7 @@ domain_socket_connect({pipe_path}) of the named pipe (Windows) to connect to Return: ~ - (`fun(dispatchers: vim.lsp.rpc.Dispatchers): - vim.lsp.rpc.PublicClient`) + (`fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`) format_rpc_error({err}) *vim.lsp.rpc.format_rpc_error()* Constructs an error message from an LSP error object. @@ -2304,12 +2300,12 @@ start({cmd}, {dispatchers}, {extra_spawn_params}) *vim.lsp.rpc.start()* Parameters: ~ • {cmd} (`string[]`) Command to start the LSP server. • {dispatchers} (`table?`) Dispatchers for LSP message types. - • {notification} (`fun(method: string, params: - table)`) - • {server_request} (`fun(method: string, params: - table): any?, lsp.ResponseError?`) - • {on_exit} (`fun(code: integer, signal: - integer)`) + • {notification} + (`fun(method: string, params: table)`) + • {server_request} + (`fun(method: string, params: table): any?, lsp.ResponseError?`) + • {on_exit} + (`fun(code: integer, signal: integer)`) • {on_error} (`fun(code: integer, err: any)`) • {extra_spawn_params} (`table?`) Additional context for the LSP server process. diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 03e9ca4dd9..367b5c36d2 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -1408,8 +1408,8 @@ Option:remove({value}) *vim.opt:remove()* vim.bo *vim.bo* Get or set buffer-scoped |options| for the buffer with number {bufnr}. If - [{bufnr}] is omitted then the current buffer is used. Invalid {bufnr} or - key is an error. + {bufnr} is omitted then the current buffer is used. Invalid {bufnr} or key + is an error. Note: this is equivalent to `:setlocal` for |global-local| options and `:set` otherwise. @@ -1459,7 +1459,7 @@ vim.o *vim.o* vim.wo *vim.wo* Get or set window-scoped |options| for the window with handle {winid} and buffer with number {bufnr}. Like `:setlocal` if setting a |global-local| - option or if {bufnr} is provided, like `:set` otherwise. If [{winid}] is + option or if {bufnr} is provided, like `:set` otherwise. If {winid} is omitted then the current window is used. Invalid {winid}, {bufnr} or key is an error. @@ -2434,10 +2434,10 @@ vim.loader.find({modname}, {opts}) *vim.loader.find()* the runtime path. • {paths}? (`string[]`, default: `{}`) Extra paths to search for modname - • {patterns}? (`string[]`, default: `{"/init.lua", - ".lua"}`) List of patterns to use when searching for - modules. A pattern is a string added to the basename of - the Lua module being searched. + • {patterns}? (`string[]`, default: + `{"/init.lua", ".lua"}`) List of patterns to use when + searching for modules. A pattern is a string added to the + basename of the Lua module being searched. • {all}? (`boolean`, default: `false`) Search for all matches. @@ -3139,16 +3139,17 @@ vim.lpeg.Cc({...}) *vim.lpeg.Cc()* vim.lpeg.Cf({patt}, {func}) *vim.lpeg.Cf()* Creates a fold capture. If `patt` produces a list of captures C1 C2 ... - Cn, this capture will produce the value `func(...func(func(C1, C2), - C3)...,Cn)`, that is, it will fold (or accumulate, or reduce) the captures - from `patt` using function `func`. This capture assumes that `patt` should - produce at least one capture with at least one value (of any type), which - becomes the initial value of an accumulator. (If you need a specific - initial value, you may prefix a constant captureto `patt`.) For each - subsequent capture, LPeg calls `func` with this accumulator as the first - argument and all values produced by the capture as extra arguments; the - first result from this call becomes the new value for the accumulator. The - final value of the accumulator becomes the captured value. + Cn, this capture will produce the value + `func(...func(func(C1, C2), C3)...,Cn)`, that is, it will fold (or + accumulate, or reduce) the captures from `patt` using function `func`. + This capture assumes that `patt` should produce at least one capture with + at least one value (of any type), which becomes the initial value of an + accumulator. (If you need a specific initial value, you may prefix a + constant captureto `patt`.) For each subsequent capture, LPeg calls `func` + with this accumulator as the first argument and all values produced by the + capture as extra arguments; the first result from this call becomes the + new value for the accumulator. The final value of the accumulator becomes + the captured value. Example: >lua local number = lpeg.R('09') ^ 1 / tonumber diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index 7e2559ecd6..5f33802ad5 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -719,8 +719,8 @@ get_captures_at_pos({bufnr}, {row}, {col}) • {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 @@ -1154,8 +1154,8 @@ Query:iter_captures({node}, {source}, {start}, {stop}) Defaults to `node:end_()`. Return: ~ - (`fun(end_line: integer?): integer, TSNode, - vim.treesitter.query.TSMetadata`) capture id, capture node, metadata + (`fun(end_line: integer?): integer, TSNode, vim.treesitter.query.TSMetadata`) + capture id, capture node, metadata *Query:iter_matches()* Query:iter_matches({node}, {source}, {start}, {stop}, {opts}) diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua index b73fad6bfa..6cf77b4648 100644 --- a/runtime/lua/vim/_editor.lua +++ b/runtime/lua/vim/_editor.lua @@ -502,7 +502,7 @@ end ---@param bufnr integer Buffer number, or 0 for current buffer ---@param pos1 integer[]|string Start of region as a (line, column) tuple or |getpos()|-compatible string ---@param pos2 integer[]|string End of region as a (line, column) tuple or |getpos()|-compatible string ----@param regtype string \|setreg()|-style selection type +---@param regtype string [setreg()]-style selection type ---@param inclusive boolean Controls whether the ending column is inclusive (see also 'selection'). ---@return table region Dict of the form `{linenr = {startcol,endcol}}`. `endcol` is exclusive, and ---whole lines are returned as `{startcol,endcol} = {0,-1}`. diff --git a/runtime/lua/vim/_inspector.lua b/runtime/lua/vim/_inspector.lua index 2999630fce..afbd6211cd 100644 --- a/runtime/lua/vim/_inspector.lua +++ b/runtime/lua/vim/_inspector.lua @@ -25,7 +25,7 @@ local defaults = { ---Get all the items at a given buffer position. --- ----Can also be pretty-printed with `:Inspect!`. *:Inspect!* +---Can also be pretty-printed with `:Inspect!`. [:Inspect!]() --- ---@param bufnr? integer defaults to the current buffer ---@param row? integer row to inspect, 0-based. Defaults to the row of the current cursor @@ -143,7 +143,7 @@ end ---Show all the items at a given buffer position. --- ----Can also be shown with `:Inspect`. *:Inspect* +---Can also be shown with `:Inspect`. [:Inspect]() --- ---@param bufnr? integer defaults to the current buffer ---@param row? integer row to inspect, 0-based. Defaults to the row of the current cursor diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 94eab72291..cb4c8749b8 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -530,7 +530,7 @@ function vim.api.nvim_buf_line_count(buffer) end --- EOL of a line, continue the highlight for the rest of the --- screen line (just like for diff and cursorline highlight). --- • virt_text : virtual text to link to this mark. A list of ---- [text, highlight] tuples, each representing a text chunk +--- `[text, highlight]` tuples, each representing a text chunk --- with specified highlight. `highlight` element can either be --- a single highlight group, or an array of multiple highlight --- groups that will be stacked (highest priority last). A @@ -563,8 +563,8 @@ function vim.api.nvim_buf_line_count(buffer) end --- for "inline" virt_text. --- • virt_lines : virtual lines to add next to this mark This --- should be an array over lines, where each line in turn is an ---- array over [text, highlight] tuples. In general, buffer and ---- window options do not affect the display of the text. In +--- array over `[text, highlight]` tuples. In general, buffer +--- and window options do not affect the display of the text. In --- particular 'wrap' and 'linebreak' options do not take --- effect, so the number of extra screen lines will always --- match the size of the array. However the 'tabstop' buffer @@ -690,9 +690,9 @@ function vim.api.nvim_buf_set_option(buffer, name, value) end --- Indexing is zero-based. Row indices are end-inclusive, and column indices --- are end-exclusive. --- ---- To insert text at a given `(row, column)` location, use `start_row = ---- end_row = row` and `start_col = end_col = col`. To delete the text in a ---- range, use `replacement = {}`. +--- To insert text at a given `(row, column)` location, use +--- `start_row = end_row = row` and `start_col = end_col = col`. To delete the +--- text in a range, use `replacement = {}`. --- --- Prefer `nvim_buf_set_lines()` if you are only adding or deleting entire --- lines. @@ -903,9 +903,9 @@ function vim.api.nvim_create_augroup(name, opts) end --- • event: (string) name of the triggered event --- `autocmd-events` --- • group: (number|nil) autocommand group id, if any ---- • match: (string) expanded value of `<amatch>` ---- • buf: (number) expanded value of `<abuf>` ---- • file: (string) expanded value of `<afile>` +--- • match: (string) expanded value of <amatch> +--- • buf: (number) expanded value of <abuf> +--- • file: (string) expanded value of <afile> --- • data: (any) arbitrary data passed from --- `nvim_exec_autocmds()` --- • command (string) optional: Vim command to execute on event. @@ -960,22 +960,21 @@ function vim.api.nvim_create_namespace(name) end --- argument that contains the following keys: --- • name: (string) Command name --- • args: (string) The args passed to the command, if any ---- `<args>` +--- <args> --- • fargs: (table) The args split by unescaped whitespace ---- (when more than one argument is allowed), if any ---- `<f-args>` +--- (when more than one argument is allowed), if any <f-args> --- • nargs: (string) Number of arguments `:command-nargs` --- • bang: (boolean) "true" if the command was executed with a ---- ! modifier `<bang>` +--- ! modifier <bang> --- • line1: (number) The starting line of the command range ---- `<line1>` +--- <line1> --- • line2: (number) The final line of the command range ---- `<line2>` +--- <line2> --- • range: (number) The number of items in the command range: ---- 0, 1, or 2 `<range>` ---- • count: (number) Any count supplied `<count>` ---- • reg: (string) The optional register, if specified `<reg>` ---- • mods: (string) Command modifiers, if any `<mods>` +--- 0, 1, or 2 <range> +--- • count: (number) Any count supplied <count> +--- • reg: (string) The optional register, if specified <reg> +--- • mods: (string) Command modifiers, if any <mods> --- • smods: (table) Command modifiers in a structured format. --- Has the same structure as the "mods" key of --- `nvim_parse_cmd()`. @@ -1049,9 +1048,9 @@ function vim.api.nvim_del_var(name) end --- Echo a message. --- ---- @param chunks any[] A list of [text, hl_group] arrays, each representing a text ---- chunk with specified highlight. `hl_group` element can be ---- omitted for no highlight. +--- @param chunks any[] A list of `[text, hl_group]` arrays, each representing a +--- text chunk with specified highlight. `hl_group` element can +--- be omitted for no highlight. --- @param history boolean if true, add to `message-history`. --- @param opts vim.api.keyset.echo_opts Optional parameters. --- • verbose: Message was printed as a result of 'verbose' option @@ -1134,7 +1133,7 @@ function vim.api.nvim_exec2(src, opts) end --- • buffer (integer) optional: buffer number `autocmd-buflocal`. --- Cannot be used with {pattern}. --- • modeline (bool) optional: defaults to true. Process the ---- modeline after the autocommands `<nomodeline>`. +--- modeline after the autocommands <nomodeline>. --- • data (any): arbitrary data to send to the autocommand --- callback. See `nvim_create_autocmd()` for details. function vim.api.nvim_exec_autocmds(event, opts) end @@ -1541,7 +1540,7 @@ function vim.api.nvim_notify(msg, log_level, opts) end --- be to the pty master end. For instance, a carriage return is --- sent as a "\r", not as a "\n". `textlock` applies. It is --- possible to call `nvim_chan_send()` directly in the callback ---- however. ["input", term, bufnr, data] +--- however. `["input", term, bufnr, data]` --- • force_crlf: (boolean, default true) Convert "\n" to "\r\n". --- @return integer function vim.api.nvim_open_term(buffer, opts) end @@ -1625,9 +1624,9 @@ function vim.api.nvim_open_term(buffer, opts) end --- • width: Window width (in character cells). Minimum of 1. --- • height: Window height (in character cells). Minimum of 1. --- • bufpos: Places float relative to buffer text (only when ---- relative="win"). Takes a tuple of zero-indexed [line, ---- column]. `row` and `col` if given are applied relative to ---- this position, else they default to: +--- relative="win"). Takes a tuple of zero-indexed +--- `[line, column]`. `row` and `col` if given are applied +--- relative to this position, else they default to: --- • `row=1` and `col=0` if `anchor` is "NW" or "NE" --- • `row=0` and `col=0` if `anchor` is "SW" or "SE" (thus --- like a tooltip near the buffer text). @@ -1756,8 +1755,8 @@ function vim.api.nvim_parse_cmd(str, opts) end --- operator/space, though also yielding an error). --- • "l" when needing to start parsing with lvalues for ":let" --- or ":for". Common flag sets: ---- • "m" to parse like for ":echo". ---- • "E" to parse like for "<C-r>=". +--- • "m" to parse like for `":echo"`. +--- • "E" to parse like for `"<C-r>="`. --- • empty string for ":call". --- • "lm" to parse for ":let". --- @param highlight boolean If true, return value will also include "highlight" key @@ -1887,15 +1886,32 @@ function vim.api.nvim_set_current_win(window) end --- --- @param ns_id integer Namespace id from `nvim_create_namespace()` --- @param opts vim.api.keyset.set_decoration_provider Table of callbacks: ---- • on_start: called first on each screen redraw ["start", tick] +--- • on_start: called first on each screen redraw +--- ``` +--- ["start", tick] +--- ``` +--- --- • on_buf: called for each buffer being redrawn (before window ---- callbacks) ["buf", bufnr, tick] +--- callbacks) +--- ``` +--- ["buf", bufnr, tick] +--- ``` +--- --- • on_win: called when starting to redraw a specific window. ---- ["win", winid, bufnr, topline, botline] +--- ``` +--- ["win", winid, bufnr, topline, botline] +--- ``` +--- --- • on_line: called for each buffer line being redrawn. (The ---- interaction with fold lines is subject to change) ["line", ---- winid, bufnr, row] ---- • on_end: called at the end of a redraw cycle ["end", tick] +--- interaction with fold lines is subject to change) +--- ``` +--- ["line", winid, bufnr, row] +--- ``` +--- +--- • on_end: called at the end of a redraw cycle +--- ``` +--- ["end", tick] +--- ``` function vim.api.nvim_set_decoration_provider(ns_id, opts) end --- Sets a highlight group. @@ -1955,7 +1971,7 @@ function vim.api.nvim_set_hl_ns_fast(ns_id) end --- To set a buffer-local mapping, use `nvim_buf_set_keymap()`. --- --- Unlike `:map`, leading/trailing whitespace is accepted as part of the ---- {lhs} or {rhs}. Empty {rhs} is `<Nop>`. `keycodes` are replaced as usual. +--- {lhs} or {rhs}. Empty {rhs} is <Nop>. `keycodes` are replaced as usual. --- --- Example: --- @@ -1977,7 +1993,7 @@ function vim.api.nvim_set_hl_ns_fast(ns_id) end --- @param lhs string Left-hand-side `{lhs}` of the mapping. --- @param rhs string Right-hand-side `{rhs}` of the mapping. --- @param opts vim.api.keyset.keymap Optional parameters map: Accepts all `:map-arguments` as keys ---- except `<buffer>`, values are booleans (default false). Also: +--- except <buffer>, values are booleans (default false). Also: --- • "noremap" disables `recursive_mapping`, like `:noremap` --- • "desc" human-readable description. --- • "callback" Lua function called in place of {rhs}. diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua index 60dcf8c64a..13ad6cc58f 100644 --- a/runtime/lua/vim/_options.lua +++ b/runtime/lua/vim/_options.lua @@ -276,7 +276,7 @@ vim.go = setmetatable({}, { }) --- Get or set buffer-scoped |options| for the buffer with number {bufnr}. ---- If [{bufnr}] is omitted then the current buffer is used. +--- If {bufnr} is omitted then the current buffer is used. --- Invalid {bufnr} or key is an error. --- --- Note: this is equivalent to `:setlocal` for |global-local| options and `:set` otherwise. @@ -293,7 +293,7 @@ vim.bo = new_buf_opt_accessor() --- Get or set window-scoped |options| for the window with handle {winid} and --- buffer with number {bufnr}. Like `:setlocal` if setting a |global-local| option ---- or if {bufnr} is provided, like `:set` otherwise. If [{winid}] is omitted then +--- or if {bufnr} is provided, like `:set` otherwise. If {winid} is omitted then --- the current window is used. Invalid {winid}, {bufnr} or key is an error. --- --- Note: only {bufnr} with value `0` (the current buffer in the window) is diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua index 9483474a40..d5075d7d3d 100644 --- a/runtime/lua/vim/diagnostic.lua +++ b/runtime/lua/vim/diagnostic.lua @@ -2,7 +2,7 @@ local api, if_nil = vim.api, vim.F.if_nil local M = {} ---- *diagnostic-structure* +--- [diagnostic-structure]() --- --- Diagnostics use the same indexing as the rest of the Nvim API (i.e. 0-based --- rows and columns). |api-indexing| @@ -68,7 +68,7 @@ local M = {} --- --- Update diagnostics in Insert mode --- (if `false`, diagnostics are updated on |InsertLeave|) ---- (default: `false) +--- (default: `false`) --- @field update_in_insert? boolean --- --- Sort diagnostics by severity. This affects the order in which signs and diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua index 357dd35bdc..a37b7f7858 100644 --- a/runtime/lua/vim/iter.lua +++ b/runtime/lua/vim/iter.lua @@ -1,7 +1,7 @@ --- @brief --- ---- \*vim.iter()\* is an interface for |iterable|s: it wraps a table or function argument into an ---- \*Iter\* object with methods (such as |Iter:filter()| and |Iter:map()|) that transform the +--- [vim.iter()]() is an interface for [iterable]s: it wraps a table or function argument into an +--- [Iter]() object with methods (such as [Iter:filter()] and [Iter:map()]) that transform the --- underlying source data. These methods can be chained to create iterator "pipelines": the output --- of each pipeline stage is input to the next stage. The first stage depends on the type passed to --- `vim.iter()`: diff --git a/runtime/lua/vim/lsp/client.lua b/runtime/lua/vim/lsp/client.lua index d0054e073c..ff0db166d5 100644 --- a/runtime/lua/vim/lsp/client.lua +++ b/runtime/lua/vim/lsp/client.lua @@ -219,7 +219,7 @@ local validate = vim.validate --- checking. --- If {handler} is not specified and if there's no respective global --- handler, then an error will occur. ---- Returns: {status}, {[client_id]}. {status} is a boolean indicating if +--- Returns: {status}, {client_id}?. {status} is a boolean indicating if --- the notification was successful. If it is `false`, then it will always --- be `false` (the client has shutdown). --- If {status} is `true`, the function returns {request_id} as the second @@ -262,7 +262,7 @@ local validate = vim.validate --- --- Checks if a client supports a given method. --- Always returns true for unknown off-spec methods. ---- [opts] is a optional `{bufnr?: integer}` table. +--- {opts} is a optional `{bufnr?: integer}` table. --- Some language server capabilities can be file specific. --- @field supports_method fun(method: string, opts?: {bufnr: integer?}): boolean --- diff --git a/runtime/lua/vim/treesitter.lua b/runtime/lua/vim/treesitter.lua index d1215885d8..a09619f369 100644 --- a/runtime/lua/vim/treesitter.lua +++ b/runtime/lua/vim/treesitter.lua @@ -432,10 +432,10 @@ end --- --- While in the window, press "a" to toggle display of anonymous nodes, "I" to toggle the --- display of the source language of each node, "o" to toggle the query editor, and press ---- <Enter> to jump to the node under the cursor in the source buffer. Folding also works +--- [<Enter>] to jump to the node under the cursor in the source buffer. Folding also works --- (try |zo|, |zc|, etc.). --- ---- Can also be shown with `:InspectTree`. *:InspectTree* +--- Can also be shown with `:InspectTree`. [:InspectTree]() --- ---@param opts table|nil Optional options table with the following possible keys: --- - lang (string|nil): The language of the source buffer. If omitted, detect diff --git a/runtime/lua/vim/treesitter/languagetree.lua b/runtime/lua/vim/treesitter/languagetree.lua index 640477eed4..62714d3f1b 100644 --- a/runtime/lua/vim/treesitter/languagetree.lua +++ b/runtime/lua/vim/treesitter/languagetree.lua @@ -1,4 +1,4 @@ ---- @brief A \*LanguageTree\* contains a tree of parsers: the root treesitter parser for {lang} and +--- @brief A [LanguageTree]() contains a tree of parsers: the root treesitter parser for {lang} and --- any "injected" language parsers, which themselves may inject other languages, recursively. --- For example a Lua buffer containing some Vimscript commands needs multiple parsers to fully --- understand its contents. @@ -93,8 +93,8 @@ local LanguageTree = {} ---Optional arguments: ---@class vim.treesitter.LanguageTree.new.Opts ---@inlinedoc ----@field queries table<string,string> -- Deprecated ----@field injections table<string,string> +---@field queries? table<string,string> -- Deprecated +---@field injections? table<string,string> LanguageTree.__index = LanguageTree diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua index 85e477be58..a086f5e876 100644 --- a/runtime/lua/vim/treesitter/query.lua +++ b/runtime/lua/vim/treesitter/query.lua @@ -995,7 +995,7 @@ end --- Opens a live editor to query the buffer you started from. --- ---- Can also be shown with *:EditQuery*. +--- Can also be shown with [:EditQuery](). --- --- If you move the cursor to a capture name ("@foo"), text matching the capture is highlighted in --- the source buffer. The query editor is a scratch buffer, use `:write` to save it. You can find diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua index cd8748ede7..0b149700b5 100644 --- a/runtime/lua/vim/version.lua +++ b/runtime/lua/vim/version.lua @@ -12,9 +12,9 @@ --- end --- ``` --- ---- *vim.version()* returns the version of the current Nvim process. +--- [vim.version()]() returns the version of the current Nvim process. --- ---- VERSION RANGE SPEC *version-range* +--- VERSION RANGE SPEC [version-range]() --- --- A version "range spec" defines a semantic version range which can be tested against a version, --- using |vim.version.range()|. diff --git a/scripts/luacats_grammar.lua b/scripts/luacats_grammar.lua index 158541dc77..ca26c70156 100644 --- a/scripts/luacats_grammar.lua +++ b/scripts/luacats_grammar.lua @@ -173,10 +173,10 @@ local grammar = P { 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(']')), + ty_index = (Pf('[') * (v.ltype + ident + rep1(num)) * fill * P(']')), table_key = v.ty_index + lname, table_elem = v.table_key * colon * v.ltype, - ty_table = Pf('{') * comma1(v.table_elem) * Pf('}'), + ty_table = Pf('{') * comma1(v.table_elem) * fill * P('}'), fun_param = lname * opt(colon * v.ltype), ty_fun = Pf('fun') * paren(comma(lname * opt(colon * v.ltype))) * opt(colon * comma1(v.ltype)), } diff --git a/scripts/text_utils.lua b/scripts/text_utils.lua index ec0ccf668b..937408c546 100644 --- a/scripts/text_utils.lua +++ b/scripts/text_utils.lua @@ -7,12 +7,99 @@ local fmt = string.format local INDENTATION = 4 +local NBSP = string.char(160) + local M = {} local function contains(t, xs) return vim.tbl_contains(xs, t) end +--- @param txt string +--- @param srow integer +--- @param scol integer +--- @param erow? integer +--- @param ecol? integer +--- @return string +local function slice_text(txt, srow, scol, erow, ecol) + local lines = vim.split(txt, '\n') + + if srow == erow then + return lines[srow + 1]:sub(scol + 1, ecol) + end + + if erow then + -- Trim the end + for _ = erow + 2, #lines do + table.remove(lines, #lines) + end + end + + -- Trim the start + for _ = 1, srow do + table.remove(lines, 1) + end + + lines[1] = lines[1]:sub(scol + 1) + lines[#lines] = lines[#lines]:sub(1, ecol) + + return table.concat(lines, '\n') +end + +--- @param text string +--- @return nvim.text_utils.MDNode +local function parse_md_inline(text) + local parser = vim.treesitter.languagetree.new(text, 'markdown_inline') + local root = parser:parse(true)[1]:root() + + --- @param node TSNode + --- @return nvim.text_utils.MDNode? + local function extract(node) + local ntype = node:type() + + if ntype:match('^%p$') then + return + end + + --- @type table<any,any> + local ret = { type = ntype } + ret.text = vim.treesitter.get_node_text(node, text) + + local row, col = 0, 0 + + for child, child_field in node:iter_children() do + local e = extract(child) + if e and ntype == 'inline' then + local srow, scol = child:start() + if (srow == row and scol > col) or srow > row then + local t = slice_text(ret.text, row, col, srow, scol) + if t and t ~= '' then + table.insert(ret, { type = 'text', j = true, text = t }) + end + end + row, col = child:end_() + end + + if child_field then + ret[child_field] = e + else + table.insert(ret, e) + end + end + + if ntype == 'inline' and (row > 0 or col > 0) then + local t = slice_text(ret.text, row, col) + if t and t ~= '' then + table.insert(ret, { type = 'text', text = t }) + end + end + + return ret + end + + return extract(root) or {} +end + --- @param text string --- @return nvim.text_utils.MDNode local function parse_md(text) @@ -47,6 +134,10 @@ local function parse_md(text) ret.text = vim.treesitter.get_node_text(node, text) end + if ntype == 'inline' then + ret = parse_md_inline(ret.text) + end + for child, child_field in node:iter_children() do local e = extract(child) if child_field then @@ -101,20 +192,47 @@ local function render_md(node, start_indent, indent, text_width, level, is_list) local add_tag = false -- local add_tag = true + local ntype = node.type + if add_tag then - parts[#parts + 1] = '<' .. node.type .. '>' + parts[#parts + 1] = '<' .. ntype .. '>' end - if node.type == 'paragraph' then - local text = assert(node.text) - text = text:gsub('(%s)%*(%w+)%*(%s)', '%1%2%3') - text = text:gsub('(%s)_(%w+)_(%s)', '%1%2%3') - text = text:gsub('\\|', '|') - text = text:gsub('\\%*', '*') - text = text:gsub('\\_', '_') - parts[#parts + 1] = M.wrap(text, start_indent, indent, text_width) + if ntype == 'text' then + parts[#parts + 1] = node.text + elseif ntype == 'html_tag' then + error('html_tag: ' .. node.text) + elseif ntype == 'inline_link' then + vim.list_extend(parts, { '*', node[1].text, '*' }) + elseif ntype == 'shortcut_link' then + if node[1].text:find('^<.*>$') then + parts[#parts + 1] = node[1].text + else + vim.list_extend(parts, { '|', node[1].text, '|' }) + end + elseif ntype == 'backslash_escape' then + parts[#parts + 1] = node.text + elseif ntype == 'emphasis' then + parts[#parts + 1] = node.text:sub(2, -2) + elseif ntype == 'code_span' then + vim.list_extend(parts, { '`', node.text:sub(2, -2):gsub(' ', NBSP), '`' }) + elseif ntype == 'inline' then + if #node == 0 then + local text = assert(node.text) + parts[#parts + 1] = M.wrap(text, start_indent, indent, text_width) + else + for _, child in ipairs(node) do + vim.list_extend(parts, render_md(child, start_indent, indent, text_width, level + 1)) + end + end + elseif ntype == 'paragraph' then + local pparts = {} + for _, child in ipairs(node) do + vim.list_extend(pparts, render_md(child, start_indent, indent, text_width, level + 1)) + end + parts[#parts + 1] = M.wrap(table.concat(pparts), start_indent, indent, text_width) parts[#parts + 1] = '\n' - elseif node.type == 'code_fence_content' then + elseif ntype == 'code_fence_content' then local lines = vim.split(node.text:gsub('\n%s*$', ''), '\n') local cindent = indent + INDENTATION @@ -137,7 +255,7 @@ local function render_md(node, start_indent, indent, text_width, level, is_list) end parts[#parts + 1] = '\n' end - elseif node.type == 'fenced_code_block' then + elseif ntype == 'fenced_code_block' then parts[#parts + 1] = '>' for _, child in ipairs(node) do if child.type == 'info_string' then @@ -152,15 +270,15 @@ local function render_md(node, start_indent, indent, text_width, level, is_list) end end parts[#parts + 1] = '<\n' - elseif node.type == 'html_block' then + elseif ntype == 'html_block' then local text = node.text:gsub('^<pre>help', '') text = text:gsub('</pre>%s*$', '') parts[#parts + 1] = text - elseif node.type == 'list_marker_dot' then + elseif ntype == 'list_marker_dot' then parts[#parts + 1] = node.text - elseif contains(node.type, { 'list_marker_minus', 'list_marker_star' }) then + elseif contains(ntype, { 'list_marker_minus', 'list_marker_star' }) then parts[#parts + 1] = '• ' - elseif node.type == 'list_item' then + elseif ntype == 'list_item' then parts[#parts + 1] = string.rep(' ', indent) local offset = node[1].type == 'list_marker_dot' and 3 or 2 for i, child in ipairs(node) do @@ -180,7 +298,7 @@ local function render_md(node, start_indent, indent, text_width, level, is_list) parts, render_md(child, start_indent0, indent, text_width, level + 1, is_list) ) - if node.type ~= 'list' and i ~= #node then + if ntype ~= 'list' and i ~= #node then if (node[i + 1] or {}).type ~= 'list' then parts[#parts + 1] = '\n' end @@ -189,7 +307,7 @@ local function render_md(node, start_indent, indent, text_width, level, is_list) end if add_tag then - parts[#parts + 1] = '</' .. node.type .. '>' + parts[#parts + 1] = '</' .. ntype .. '>' end return parts @@ -227,7 +345,7 @@ function M.md_to_vimdoc(text, start_indent, indent, text_width, is_list) local parsed = parse_md(text .. '\n') local ret = render_md(parsed, start_indent, indent, text_width, 0, is_list) - local lines = vim.split(table.concat(ret), '\n') + local lines = vim.split(table.concat(ret):gsub(NBSP, ' '), '\n') lines = vim.tbl_map(align_tags(text_width), lines) diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c index 06f21919f9..d71bcc4bcf 100644 --- a/src/nvim/api/autocmd.c +++ b/src/nvim/api/autocmd.c @@ -386,10 +386,10 @@ cleanup: /// - id: (number) autocommand id /// - event: (string) name of the triggered event |autocmd-events| /// - group: (number|nil) autocommand group id, if any -/// - match: (string) expanded value of |<amatch>| -/// - buf: (number) expanded value of |<abuf>| -/// - file: (string) expanded value of |<afile>| -/// - data: (any) arbitrary data passed from |nvim_exec_autocmds()| +/// - match: (string) expanded value of [<amatch>] +/// - buf: (number) expanded value of [<abuf>] +/// - file: (string) expanded value of [<afile>] +/// - data: (any) arbitrary data passed from [nvim_exec_autocmds()] /// - command (string) optional: Vim command to execute on event. Cannot be used with /// {callback} /// - once (boolean) optional: defaults to false. Run the autocommand @@ -694,7 +694,7 @@ void nvim_del_augroup_by_name(String name, Error *err) /// - buffer (integer) optional: buffer number |autocmd-buflocal|. Cannot be used with /// {pattern}. /// - modeline (bool) optional: defaults to true. Process the -/// modeline after the autocommands |<nomodeline>|. +/// modeline after the autocommands [<nomodeline>]. /// - data (any): arbitrary data to send to the autocommand callback. See /// |nvim_create_autocmd()| for details. /// @see |:doautocmd| diff --git a/src/nvim/api/command.c b/src/nvim/api/command.c index e08035b0eb..779e216c74 100644 --- a/src/nvim/api/command.c +++ b/src/nvim/api/command.c @@ -48,16 +48,16 @@ /// @param[out] err Error details, if any. /// @return Dictionary containing command information, with these keys: /// - cmd: (string) Command name. -/// - range: (array) (optional) Command range (|<line1>| |<line2>|). +/// - range: (array) (optional) Command range ([<line1>] [<line2>]). /// Omitted if command doesn't accept a range. /// Otherwise, has no elements if no range was specified, one element if /// only a single range item was specified, or two elements if both range /// items were specified. -/// - count: (number) (optional) Command |<count>|. +/// - count: (number) (optional) Command [<count>]. /// Omitted if command cannot take a count. -/// - reg: (string) (optional) Command |<register>|. +/// - reg: (string) (optional) Command [<register>]. /// Omitted if command cannot take a register. -/// - bang: (boolean) Whether command contains a |<bang>| (!) modifier. +/// - bang: (boolean) Whether command contains a [<bang>] (!) modifier. /// - args: (array) Command arguments. /// - addr: (string) Value of |:command-addr|. Uses short name or "line" for -addr=lines. /// - nargs: (string) Value of |:command-nargs|. @@ -853,17 +853,17 @@ static void build_cmdline_str(char **cmdlinep, exarg_T *eap, CmdParseInfo *cmdin /// from Lua, the command can also be a Lua function. The function is called with a /// single table argument that contains the following keys: /// - name: (string) Command name -/// - args: (string) The args passed to the command, if any |<args>| +/// - args: (string) The args passed to the command, if any [<args>] /// - fargs: (table) The args split by unescaped whitespace (when more than one -/// argument is allowed), if any |<f-args>| +/// argument is allowed), if any [<f-args>] /// - nargs: (string) Number of arguments |:command-nargs| -/// - bang: (boolean) "true" if the command was executed with a ! modifier |<bang>| -/// - line1: (number) The starting line of the command range |<line1>| -/// - line2: (number) The final line of the command range |<line2>| -/// - range: (number) The number of items in the command range: 0, 1, or 2 |<range>| -/// - count: (number) Any count supplied |<count>| -/// - reg: (string) The optional register, if specified |<reg>| -/// - mods: (string) Command modifiers, if any |<mods>| +/// - bang: (boolean) "true" if the command was executed with a ! modifier [<bang>] +/// - line1: (number) The starting line of the command range [<line1>] +/// - line2: (number) The final line of the command range [<line2>] +/// - range: (number) The number of items in the command range: 0, 1, or 2 [<range>] +/// - count: (number) Any count supplied [<count>] +/// - reg: (string) The optional register, if specified [<reg>] +/// - mods: (string) Command modifiers, if any [<mods>] /// - smods: (table) Command modifiers in a structured format. Has the same /// structure as the "mods" key of |nvim_parse_cmd()|. /// @param opts Optional |command-attributes|. diff --git a/src/nvim/api/extmark.c b/src/nvim/api/extmark.c index e35840915f..1b03a97edb 100644 --- a/src/nvim/api/extmark.c +++ b/src/nvim/api/extmark.c @@ -43,7 +43,7 @@ void api_extmark_free_all_mem(void) map_destroy(String, &namespace_ids); } -/// Creates a new namespace or gets an existing one. \*namespace\* +/// Creates a new namespace or gets an existing one. [namespace]() /// /// Namespaces are used for buffer highlights and virtual text, see /// |nvim_buf_add_highlight()| and |nvim_buf_set_extmark()|. @@ -284,7 +284,7 @@ ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id, /// their start position is less than `start` /// - type: Filter marks by type: "highlight", "sign", "virt_text" and "virt_lines" /// @param[out] err Error details, if any -/// @return List of [extmark_id, row, col] tuples in "traversal order". +/// @return List of `[extmark_id, row, col]` tuples in "traversal order". Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, Object start, Object end, Dict(get_extmarks) *opts, Arena *arena, Error *err) FUNC_API_SINCE(7) @@ -390,7 +390,7 @@ Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, Object start, Object e /// of the screen line (just like for diff and /// cursorline highlight). /// - virt_text : virtual text to link to this mark. -/// A list of [text, highlight] tuples, each representing a +/// A list of `[text, highlight]` tuples, each representing a /// text chunk with specified highlight. `highlight` element /// can either be a single highlight group, or an array of /// multiple highlight groups that will be stacked @@ -425,7 +425,7 @@ Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, Object start, Object e /// /// - virt_lines : virtual lines to add next to this mark /// This should be an array over lines, where each line in -/// turn is an array over [text, highlight] tuples. In +/// turn is an array over `[text, highlight]` tuples. In /// general, buffer and window options do not affect the /// display of the text. In particular 'wrap' /// and 'linebreak' options do not take effect, so @@ -1040,17 +1040,27 @@ void nvim_buf_clear_namespace(Buffer buffer, Integer ns_id, Integer line_start, /// @param ns_id Namespace id from |nvim_create_namespace()| /// @param opts Table of callbacks: /// - on_start: called first on each screen redraw +/// ``` /// ["start", tick] +/// ``` /// - on_buf: called for each buffer being redrawn (before -/// window callbacks) +/// window callbacks) +/// ``` /// ["buf", bufnr, tick] +/// ``` /// - on_win: called when starting to redraw a specific window. +/// ``` /// ["win", winid, bufnr, topline, botline] +/// ``` /// - on_line: called for each buffer line being redrawn. /// (The interaction with fold lines is subject to change) +/// ``` /// ["line", winid, bufnr, row] +/// ``` /// - on_end: called at the end of a redraw cycle +/// ``` /// ["end", tick] +/// ``` void nvim_set_decoration_provider(Integer ns_id, Dict(set_decoration_provider) *opts, Error *err) FUNC_API_SINCE(7) FUNC_API_LUA_ONLY { diff --git a/src/nvim/api/ui.c b/src/nvim/api/ui.c index 02433b037c..692e3f95fc 100644 --- a/src/nvim/api/ui.c +++ b/src/nvim/api/ui.c @@ -410,7 +410,7 @@ void nvim_ui_try_resize_grid(uint64_t channel_id, Integer grid, Integer width, I } /// Tells Nvim the number of elements displaying in the popupmenu, to decide -/// <PageUp> and <PageDown> movement. +/// [<PageUp>] and [<PageDown>] movement. /// /// @param channel_id /// @param height Popupmenu height, must be greater than zero. diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 6a3c6bab67..84a2f24dbc 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -249,7 +249,7 @@ void nvim_set_hl_ns_fast(Integer ns_id, Error *err) /// /// On execution error: does not fail, but updates v:errmsg. /// -/// To input sequences like <C-o> use |nvim_replace_termcodes()| (typically +/// To input sequences like [<C-o>] use |nvim_replace_termcodes()| (typically /// with escape_ks=false) to replace |keycodes|, then pass the result to /// nvim_feedkeys(). /// @@ -337,11 +337,11 @@ void nvim_feedkeys(String keys, String mode, Boolean escape_ks) /// /// On execution error: does not fail, but updates v:errmsg. /// -/// @note |keycodes| like <CR> are translated, so "<" is special. -/// To input a literal "<", send <LT>. +/// @note |keycodes| like [<CR>] are translated, so "<" is special. +/// To input a literal "<", send [<LT>]. /// /// @note For mouse events use |nvim_input_mouse()|. The pseudokey form -/// "<LeftMouse><col,row>" is deprecated since |api-level| 6. +/// `<LeftMouse><col,row>` is deprecated since |api-level| 6. /// /// @param keys to be typed /// @return Number of bytes actually written (can be fewer than @@ -362,7 +362,7 @@ Integer nvim_input(String keys) /// by calling it multiple times in a loop: the intermediate mouse /// positions will be ignored. It should be used to implement real-time /// mouse input in a GUI. The deprecated pseudokey form -/// ("<LeftMouse><col,row>") of |nvim_input()| has the same limitation. +/// (`<LeftMouse><col,row>`) of |nvim_input()| has the same limitation. /// /// @param button Mouse button: one of "left", "right", "middle", "wheel", "move", /// "x1", "x2". @@ -451,13 +451,13 @@ error: "invalid button or action"); } -/// Replaces terminal codes and |keycodes| (<CR>, <Esc>, ...) in a string with +/// Replaces terminal codes and |keycodes| ([<CR>], [<Esc>], ...) in a string with /// the internal representation. /// /// @param str String to be converted. /// @param from_part Legacy Vim parameter. Usually true. -/// @param do_lt Also translate <lt>. Ignored if `special` is false. -/// @param special Replace |keycodes|, e.g. <CR> becomes a "\r" char. +/// @param do_lt Also translate [<lt>]. Ignored if `special` is false. +/// @param special Replace |keycodes|, e.g. [<CR>] becomes a "\r" char. /// @see replace_termcodes /// @see cpoptions String nvim_replace_termcodes(String str, Boolean from_part, Boolean do_lt, Boolean special) @@ -525,7 +525,7 @@ Object nvim_notify(String msg, Integer log_level, Dictionary opts, Arena *arena, } /// Calculates the number of display cells occupied by `text`. -/// Control characters including <Tab> count as one cell. +/// Control characters including [<Tab>] count as one cell. /// /// @param text Some text /// @param[out] err Error details, if any @@ -762,7 +762,7 @@ void nvim_set_vvar(String name, Object value, Error *err) /// Echo a message. /// -/// @param chunks A list of [text, hl_group] arrays, each representing a +/// @param chunks A list of `[text, hl_group]` arrays, each representing a /// text chunk with specified highlight. `hl_group` element /// can be omitted for no highlight. /// @param history if true, add to |message-history|. @@ -1019,7 +1019,7 @@ fail: /// master end. For instance, a carriage return is sent /// as a "\r", not as a "\n". |textlock| applies. It is possible /// to call |nvim_chan_send()| directly in the callback however. -/// ["input", term, bufnr, data] +/// `["input", term, bufnr, data]` /// - force_crlf: (boolean, default true) Convert "\n" to "\r\n". /// @param[out] err Error details, if any /// @return Channel id, or 0 on error @@ -1471,7 +1471,7 @@ ArrayOf(Dictionary) nvim_get_keymap(String mode, Arena *arena) /// To set a buffer-local mapping, use |nvim_buf_set_keymap()|. /// /// Unlike |:map|, leading/trailing whitespace is accepted as part of the {lhs} or {rhs}. -/// Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual. +/// Empty {rhs} is [<Nop>]. |keycodes| are replaced as usual. /// /// Example: /// @@ -1491,7 +1491,7 @@ ArrayOf(Dictionary) nvim_get_keymap(String mode, Arena *arena) /// "ia", "ca" or "!a" for abbreviation in Insert mode, Cmdline mode, or both, respectively /// @param lhs Left-hand-side |{lhs}| of the mapping. /// @param rhs Right-hand-side |{rhs}| of the mapping. -/// @param opts Optional parameters map: Accepts all |:map-arguments| as keys except |<buffer>|, +/// @param opts Optional parameters map: Accepts all |:map-arguments| as keys except [<buffer>], /// values are booleans (default false). Also: /// - "noremap" disables |recursive_mapping|, like |:noremap| /// - "desc" human-readable description. @@ -1521,7 +1521,7 @@ void nvim_del_keymap(uint64_t channel_id, String mode, String lhs, Error *err) /// Returns a 2-tuple (Array), where item 0 is the current channel id and item /// 1 is the |api-metadata| map (Dictionary). /// -/// @returns 2-tuple [{channel-id}, {api-metadata}] +/// @returns 2-tuple `[{channel-id}, {api-metadata}]` Array nvim_get_api_info(uint64_t channel_id, Arena *arena) FUNC_API_SINCE(1) FUNC_API_FAST FUNC_API_REMOTE_ONLY { @@ -1960,7 +1960,7 @@ Object nvim_get_proc(Integer pid, Arena *arena, Error *err) /// If neither |ins-completion| nor |cmdline-completion| popup menu is active /// this API call is silently ignored. /// Useful for an external UI using |ui-popupmenu| to control the popup menu with the mouse. -/// Can also be used in a mapping; use <Cmd> |:map-cmd| or a Lua mapping to ensure the mapping +/// Can also be used in a mapping; use [<Cmd>] |:map-cmd| or a Lua mapping to ensure the mapping /// doesn't end completion mode. /// /// @param item Index (zero-based) of the item to select. Value of -1 selects nothing diff --git a/src/nvim/api/vimscript.c b/src/nvim/api/vimscript.c index 8f57e61c76..477cbe2428 100644 --- a/src/nvim/api/vimscript.c +++ b/src/nvim/api/vimscript.c @@ -365,8 +365,8 @@ typedef kvec_withinit_t(ExprASTConvStackItem, 16) ExprASTConvStack; /// - "l" when needing to start parsing with lvalues for /// ":let" or ":for". /// Common flag sets: -/// - "m" to parse like for ":echo". -/// - "E" to parse like for "<C-r>=". +/// - "m" to parse like for `":echo"`. +/// - "E" to parse like for `"<C-r>="`. /// - empty string for ":call". /// - "lm" to parse for ":let". /// @param[in] highlight If true, return value will also include "highlight" @@ -390,7 +390,7 @@ typedef kvec_withinit_t(ExprASTConvStackItem, 16) ExprASTConvStack; /// - "ast": AST, either nil or a dictionary with these keys: /// - "type": node type, one of the value names from ExprASTNodeType /// stringified without "kExprNode" prefix. -/// - "start": a pair [line, column] describing where node is "started" +/// - "start": a pair `[line, column]` describing where node is "started" /// where "line" is always 0 (will not be 0 if you will be /// using this API on e.g. ":let", but that is not /// present yet). Both elements are Integers. diff --git a/src/nvim/api/win_config.c b/src/nvim/api/win_config.c index 3cc520dc78..543c7b8113 100644 --- a/src/nvim/api/win_config.c +++ b/src/nvim/api/win_config.c @@ -116,7 +116,7 @@ /// - width: Window width (in character cells). Minimum of 1. /// - height: Window height (in character cells). Minimum of 1. /// - bufpos: Places float relative to buffer text (only when -/// relative="win"). Takes a tuple of zero-indexed [line, column]. +/// relative="win"). Takes a tuple of zero-indexed `[line, column]`. /// `row` and `col` if given are applied relative to this /// position, else they default to: /// - `row=1` and `col=0` if `anchor` is "NW" or "NE" diff --git a/test/functional/script/luacats_grammar_spec.lua b/test/functional/script/luacats_grammar_spec.lua index 0fc2e4b95a..c3ac9fe722 100644 --- a/test/functional/script/luacats_grammar_spec.lua +++ b/test/functional/script/luacats_grammar_spec.lua @@ -139,4 +139,16 @@ describe('luacats grammar', function() type = 'string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)', } ) + + test('@field [integer] integer', { + kind = 'field', + name = '[integer]', + type = 'integer', + }) + + test('@field [1] integer', { + kind = 'field', + name = '[1]', + type = 'integer', + }) end) diff --git a/test/functional/script/text_utils_spec.lua b/test/functional/script/text_utils_spec.lua index e644df92ae..190c617e1d 100644 --- a/test/functional/script/text_utils_spec.lua +++ b/test/functional/script/text_utils_spec.lua @@ -55,4 +55,6 @@ describe('md_to_vimdoc', function() ' para2', '', }, 0, 10, 78) + + test('inline 1', { '(`string`)' }, { '(`string`)', '' }) end) |