diff options
| -rw-r--r-- | MAINTAIN.md | 24 | ||||
| -rw-r--r-- | runtime/doc/api.txt | 78 | ||||
| -rw-r--r-- | runtime/doc/diagnostic.txt | 4 | ||||
| -rw-r--r-- | runtime/doc/lsp.txt | 15 | ||||
| -rw-r--r-- | runtime/doc/lua.txt | 55 | ||||
| -rw-r--r-- | runtime/doc/treesitter.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/vim_diff.txt | 10 | ||||
| -rw-r--r-- | runtime/lua/vim/_editor.lua | 38 | ||||
| -rwxr-xr-x | scripts/gen_vimdoc.py | 28 | ||||
| -rw-r--r-- | src/nvim/api/buffer.c | 5 | ||||
| -rw-r--r-- | src/nvim/api/vim.c | 15 |
11 files changed, 148 insertions, 126 deletions
diff --git a/MAINTAIN.md b/MAINTAIN.md index 191ef70709..e280085aa8 100644 --- a/MAINTAIN.md +++ b/MAINTAIN.md @@ -128,17 +128,25 @@ These dependencies are "vendored" (inlined), we must update the sources manually We may maintain forks, if we are waiting on upstream changes: https://github.com/neovim/neovim/wiki/Deps -CI --------------- +Non-technical dependencies +-------------------------- -### General +* Domain names (held in https://namecheap.com): + * neovim.org + * neovim.io + * packspec.org + * pkgjson.org + +Automation (CI) +--------------- -As our CI is primarily dependent on GitHub Actions at the moment, then so will -our CI strategy be. The following guidelines have worked well for us so far: +Our CI and automation jobs are primarily driven by GitHub Actions. Guidelines: + +### General -* Never use a macOS runner if an Ubuntu or a Windows runner can be used - instead. This is because macOS runners have a [tighter restrictions on the - number of concurrent jobs](https://docs.github.com/en/actions/learn-github-actions/usage-limits-billing-and-administration#usage-limits). +* Avoid macOS if an Ubuntu or a Windows runner can be used instead. This is + because macOS runners have [tighter restrictions on the number of concurrent + jobs](https://docs.github.com/en/actions/learn-github-actions/usage-limits-billing-and-administration#usage-limits). ### Runner versions diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 46c5f2ea18..d96169066c 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -727,8 +727,8 @@ nvim_del_keymap({mode}, {lhs}) *nvim_del_keymap()* nvim_del_mark({name}) *nvim_del_mark()* Deletes an uppercase/file named mark. See |mark-motions|. - Note: - fails with error if a lowercase or buffer local named mark is used. + Note: ~ + • Lowercase name (or other buffer-local mark) is an error. Parameters: ~ • {name} Mark name @@ -952,6 +952,10 @@ nvim_get_current_win() *nvim_get_current_win()* nvim_get_hl({ns_id}, {*opts}) *nvim_get_hl()* Gets all or specific highlight groups in a namespace. + Note: ~ + • When the `link` attribute is defined in the highlight definition map, + other attributes will not be taking effect (see |:hi-link|). + Parameters: ~ • {ns_id} Get highlight groups for namespace ns_id |nvim_get_namespaces()|. Use 0 to get global highlight groups @@ -967,10 +971,6 @@ nvim_get_hl({ns_id}, {*opts}) *nvim_get_hl()* map as in |nvim_set_hl()|, or only a single highlight definition map if requested by name or id. - Note: - When the `link` attribute is defined in the highlight definition map, - other attributes will not be taking effect (see |:hi-link|). - nvim_get_hl_id_by_name({name}) *nvim_get_hl_id_by_name()* Gets a highlight group by name @@ -987,13 +987,14 @@ nvim_get_keymap({mode}) *nvim_get_keymap()* "buffer" key is always zero. nvim_get_mark({name}, {opts}) *nvim_get_mark()* - Return a tuple (row, col, buffer, buffername) representing the position of - the uppercase/file named mark. See |mark-motions|. + Returns a `(row, col, buffer, buffername)` tuple representing the position + of the uppercase/file named mark. "End of line" column position is + returned as |v:maxcol| (big number). See |mark-motions|. Marks are (1,0)-indexed. |api-indexing| - Note: - fails with error if a lowercase or buffer local named mark is used. + Note: ~ + • Lowercase name (or other buffer-local mark) is an error. Parameters: ~ • {name} Mark name @@ -1074,12 +1075,10 @@ nvim_input({keys}) *nvim_input()* On execution error: does not fail, but updates v:errmsg. - Note: - |keycodes| like <CR> are translated, so "<" is special. To input a + 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 + • For mouse events use |nvim_input_mouse()|. The pseudokey form "<LeftMouse><col,row>" is deprecated since |api-level| 6. Attributes: ~ @@ -1099,8 +1098,8 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col}) Non-blocking: does not wait on any result, but queues the event to be processed soon by the event loop. - Note: - Currently this doesn't support "scripting" multiple mouse events by + Note: ~ + • 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 @@ -1316,8 +1315,8 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) appropriate. Example: library first identifies the channel, then a plugin using that library later identifies itself. - Note: - "Something is better than nothing". You don't need to include all the + Note: ~ + • "Something is better than nothing". You don't need to include all the fields. Attributes: ~ @@ -1409,21 +1408,17 @@ nvim_set_current_win({window}) *nvim_set_current_win()* nvim_set_hl({ns_id}, {name}, {*val}) *nvim_set_hl()* Sets a highlight group. - Note: - Unlike the `:highlight` command which can update a highlight group, - this function completely replaces the definition. For example: + Note: ~ + • Unlike the `:highlight` command which can update a highlight group, this + function completely replaces the definition. For example: `nvim_set_hl(0, 'Visual', {})` will clear the highlight group 'Visual'. - - Note: - The fg and bg keys also accept the string values `"fg"` or `"bg"` - which act as aliases to the corresponding foreground and background - values of the Normal group. If the Normal group has not been defined, - using these values results in an error. - - Note: - If `link` is used in combination with other attributes; only the - `link` will take effect (see |:hi-link|). + • The fg and bg keys also accept the string values `"fg"` or `"bg"` which + act as aliases to the corresponding foreground and background values + of the Normal group. If the Normal group has not been defined, using + these values results in an error. + • If `link` is used in combination with other attributes; only the `link` + will take effect (see |:hi-link|). Parameters: ~ • {ns_id} Namespace id for this highlight |nvim_create_namespace()|. @@ -2140,8 +2135,8 @@ nvim_buf_del_keymap({buffer}, {mode}, {lhs}) *nvim_buf_del_keymap()* nvim_buf_del_mark({buffer}, {name}) *nvim_buf_del_mark()* Deletes a named mark in the buffer. See |mark-motions|. - Note: - only deletes marks set in the buffer, if the mark is not set in the + Note: ~ + • only deletes marks set in the buffer, if the mark is not set in the buffer it will return false. Parameters: ~ @@ -2232,7 +2227,8 @@ nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing}) Array of lines, or empty array for unloaded buffer. nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()* - Returns a tuple (row,col) representing the position of the named mark. See + Returns a `(row,col)` tuple representing the position of the named mark. + "End of line" column position is returned as |v:maxcol| (big number). See |mark-motions|. Marks are (1,0)-indexed. |api-indexing| @@ -2323,8 +2319,8 @@ nvim_buf_is_loaded({buffer}) *nvim_buf_is_loaded()* nvim_buf_is_valid({buffer}) *nvim_buf_is_valid()* Checks if a buffer is valid. - Note: - Even if a buffer is valid it may have been unloaded. See |api-buffer| + Note: ~ + • Even if a buffer is valid it may have been unloaded. See |api-buffer| for more info about unloaded buffers. Parameters: ~ @@ -2386,8 +2382,8 @@ nvim_buf_set_mark({buffer}, {name}, {line}, {col}, {opts}) Marks are (1,0)-indexed. |api-indexing| - Note: - Passing 0 as line deletes the mark + Note: ~ + • Passing 0 as line deletes the mark Parameters: ~ • {buffer} Buffer to set the mark on @@ -3442,8 +3438,8 @@ nvim_ui_attach({width}, {height}, {options}) *nvim_ui_attach()* Implies that the client is ready to show the UI. Adds the client to the list of UIs. |nvim_list_uis()| - Note: - If multiple UI clients are attached, the global screen dimensions + Note: ~ + • If multiple UI clients are attached, the global screen dimensions degrade to the smallest client. E.g. if client A requests 80x40 but client B requests 200x100, the global screen has size 80x40. diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt index 9dd42061ef..4b2b5e5f9a 100644 --- a/runtime/doc/diagnostic.txt +++ b/runtime/doc/diagnostic.txt @@ -361,8 +361,8 @@ config({opts}, {namespace}) *vim.diagnostic.config()* then virtual text will not be enabled for those diagnostics. - Note: - Each of the configuration options below accepts one of the following: + Note: ~ + • Each of the configuration options below accepts one of the following: • `false`: Disable this feature • `true`: Enable this feature, use default settings. • `table`: Enable this feature with overrides. Use an empty table to diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index b21c1d6e9d..7bec93de89 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -680,7 +680,7 @@ buf_request_sync({bufnr}, {method}, {params}, {timeout_ms}) • {timeout_ms} (integer|nil) Maximum time in milliseconds to wait for a result. Defaults to 1000 - Return: ~ + Return (multiple): ~ (table) result Map of client_id:request_result. (string|nil) err On timeout, cancel, or error, `err` is a string describing the failure reason, and `result` is nil. @@ -1126,8 +1126,9 @@ completion({context}) *vim.lsp.buf.completion()* declaration({options}) *vim.lsp.buf.declaration()* Jumps to the declaration of the symbol under the cursor. - Note: - Many servers do not implement this method. Generally, see + + Note: ~ + • Many servers do not implement this method. Generally, see |vim.lsp.buf.definition()| instead. Parameters: ~ @@ -1623,7 +1624,7 @@ convert_signature_help_to_markdown_lines({signature_help}, {ft}, {triggers}) • {triggers} (table|nil) list of trigger characters from the lsp server. used to better determine parameter offsets - Return: ~ + Return (multiple): ~ (table|nil) table list of lines of converted markdown. (table|nil) table of active hl @@ -1833,7 +1834,7 @@ open_floating_preview({contents}, {syntax}, {opts}) {focusable} is also `true`, focus an existing floating window with the same {focus_id} - Return: ~ + Return (multiple): ~ (integer) bufnr of newly created float window (integer) winid of newly created float window preview window @@ -1857,7 +1858,7 @@ preview_location({location}, {opts}) *vim.lsp.util.preview_location()* Parameters: ~ • {location} (table) a single `Location` or `LocationLink` - Return: ~ + Return (multiple): ~ (integer|nil) buffer id of float window (integer|nil) window id of float window @@ -2091,7 +2092,7 @@ start({cmd}, {cmd_args}, {dispatchers}, {extra_spawn_params}) • {env} (table) Additional environment variables for LSP server process - Return: ~ + Return (multiple): ~ Client RPC object. Methods: • `notify()` |vim.lsp.rpc.notify()| diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 63523c32d5..9e4815bea5 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -1475,17 +1475,15 @@ on_key({fn}, {ns_id}) *vim.on_key()* The Nvim command-line option |-w| is related but does not support callbacks and cannot be toggled dynamically. - Note: - {fn} will not be cleared by |nvim_buf_clear_namespace()| - - Note: - {fn} will receive the keys after mappings have been evaluated + Note: ~ + • {fn} will be removed on error. + • {fn} will not be cleared by |nvim_buf_clear_namespace()| + • {fn} will receive the keys after mappings have been evaluated Parameters: ~ - • {fn} (function) Callback function. It should take one string - argument. On each key press, Nvim passes the key char to - fn(). |i_CTRL-V| If {fn} is nil, it removes the callback for - the associated {ns_id} + • {fn} fun(key: string) Function invoked on every key press. + |i_CTRL-V| Returning nil removes the callback associated with + namespace {ns_id}. • {ns_id} integer? Namespace ID. If nil or 0, generates and returns a new |nvim_create_namespace()| id. @@ -1493,9 +1491,6 @@ on_key({fn}, {ns_id}) *vim.on_key()* (integer) Namespace id associated with {fn}. Or count of all callbacks if on_key() is called without arguments. - Note: - {fn} will be removed if an error occurs while calling. - paste({lines}, {phase}) *vim.paste()* Paste handler, invoked by |nvim_paste()| when a conforming UI (such as the |TUI|) pastes text into the editor. @@ -1543,22 +1538,26 @@ print({...}) *vim.print()* • |:=| region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive}) *vim.region()* - Get a table of lines with start, end columns for a region marked by two - points. Input and output positions are (0,0)-indexed and indicate byte - positions. + Gets a dict of line segment ("chunk") positions for the region from `pos1` + to `pos2`. + + Input and output positions are byte positions, (0,0)-indexed. "End of + line" column position (for example, |linewise| visual selection) is + returned as |v:maxcol| (big number). Parameters: ~ - • {bufnr} (integer) number of buffer - • {pos1} integer[]|string start of region as a (line, column) - tuple or string accepted by |getpos()| - • {pos2} integer[]|string end of region as a (line, column) tuple - or string accepted by |getpos()| - • {regtype} (string) type of selection, see |setreg()| - • {inclusive} (boolean) indicating whether column of pos2 is inclusive + • {bufnr} (integer) Buffer number, or 0 for current buffer + • {pos1} integer[]|string Start of region as a (line, column) + tuple or |getpos()|-compatible string + • {pos2} integer[]|string End of region as a (line, column) tuple + or |getpos()|-compatible string + • {regtype} (string) |setreg()|-style selection type + • {inclusive} (boolean) Controls whether `pos2` column is inclusive + (see also 'selection'). Return: ~ - (table) region Table of the form `{linenr = {startcol,endcol}}`. - `endcol` is exclusive, and whole lines are marked with + (table) region Dict of the form `{linenr = {startcol,endcol}}`. + `endcol` is exclusive, and whole lines are returned as `{startcol,endcol} = {0,-1}`. schedule_wrap({cb}) *vim.schedule_wrap()* @@ -2361,7 +2360,7 @@ open({path}) *vim.ui.open()* Parameters: ~ • {path} (string) Path or URL to open - Return: ~ + Return (multiple): ~ SystemCompleted|nil # Command result, or nil if not found. (string|nil) # Error message on failure @@ -2564,7 +2563,7 @@ match({args}) *vim.filetype.match()* contents to use for matching. Can be used with {filename}. Mutually exclusive with {buf}. - Return: ~ + Return (multiple): ~ (string|nil) If a match was found, the matched filetype. (function|nil) A function that modifies buffer state when called (for example, to set some filetype specific buffer variables). The function @@ -2909,8 +2908,8 @@ cmp({v1}, {v2}) *vim.version.cmp()* end < - Note: - Per semver, build metadata is ignored when comparing two + Note: ~ + • Per semver, build metadata is ignored when comparing two otherwise-equivalent versions. Parameters: ~ diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index 7539417197..070659ce3d 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -617,7 +617,7 @@ get_node_range({node_or_range}) *vim.treesitter.get_node_range()* Parameters: ~ • {node_or_range} (|TSNode| | table) Node or table of positions - Return: ~ + Return (multiple): ~ (integer) start_row (integer) start_col (integer) end_row diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index 6ffd45d013..68ebb8cc94 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -536,12 +536,14 @@ Working directory (Vim implemented some of these after Nvim): working directory. Use `getcwd(-1, -1)` to get the global working directory. ============================================================================== -Missing legacy features *nvim-missing* +Missing features *nvim-missing* These legacy Vim features are not yet implemented: -*:gui* -*:gvim* +- *:gui* +- *:gvim* +- *'completepopup'* +- *'previewpopup'* ============================================================================== Removed legacy features *nvim-removed* @@ -644,6 +646,7 @@ Options: 'highlight' (Names of builtin |highlight-groups| cannot be changed.) *'hkmap'* *'hk'* use `set keymap=hebrew` instead. *'hkmapp'* *'hkp'* use `set keymap=hebrewp` instead. + keyprotocol *'pastetoggle'* *'pt'* Just Paste It.™ |paste| is handled automatically when you paste text using your terminal's or GUI's paste feature (CTRL-SHIFT-v, @@ -687,6 +690,7 @@ Options: Use |g8| or |ga|. See |mbyte-combining|. *'maxmem'* Nvim delegates memory-management to the OS. *'maxmemtot'* Nvim delegates memory-management to the OS. + printoptions *'printdevice'* *'printencoding'* *'printexpr'* diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua index 6f701e9ae9..80e7518b01 100644 --- a/runtime/lua/vim/_editor.lua +++ b/runtime/lua/vim/_editor.lua @@ -460,17 +460,18 @@ do vim.t = make_dict_accessor('t') end ---- Get a table of lines with start, end columns for a region marked by two points. ---- Input and output positions are (0,0)-indexed and indicate byte positions. +--- Gets a dict of line segment ("chunk") positions for the region from `pos1` to `pos2`. --- ----@param bufnr integer number of buffer ----@param pos1 integer[]|string start of region as a (line, column) tuple or string accepted by |getpos()| ----@param pos2 integer[]|string end of region as a (line, column) tuple or string accepted by |getpos()| ----@param regtype string type of selection, see |setreg()| ----@param inclusive boolean indicating whether column of pos2 is inclusive ----@return table region Table of the form `{linenr = {startcol,endcol}}`. ---- `endcol` is exclusive, and whole lines are marked with ---- `{startcol,endcol} = {0,-1}`. +--- Input and output positions are byte positions, (0,0)-indexed. "End of line" column +--- position (for example, |linewise| visual selection) is returned as |v:maxcol| (big number). +--- +---@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 inclusive boolean Controls whether `pos2` 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}`. function vim.region(bufnr, pos1, pos2, regtype, inclusive) if not vim.api.nvim_buf_is_loaded(bufnr) then vim.fn.bufload(bufnr) @@ -610,18 +611,17 @@ local on_key_cbs = {} --- The Nvim command-line option |-w| is related but does not support callbacks --- and cannot be toggled dynamically. --- ----@param fn function: Callback function. It should take one string argument. ---- On each key press, Nvim passes the key char to fn(). |i_CTRL-V| ---- If {fn} is nil, it removes the callback for the associated {ns_id} +---@note {fn} will be removed on error. +---@note {fn} will not be cleared by |nvim_buf_clear_namespace()| +---@note {fn} will receive the keys after mappings have been evaluated +--- +---@param fn fun(key: string) Function invoked on every key press. |i_CTRL-V| +--- Returning nil removes the callback associated with namespace {ns_id}. ---@param ns_id integer? Namespace ID. If nil or 0, generates and returns a new --- |nvim_create_namespace()| id. --- ---@return integer Namespace id associated with {fn}. Or count of all callbacks ---if on_key() is called without arguments. ---- ----@note {fn} will be removed if an error occurs while calling. ----@note {fn} will not be cleared by |nvim_buf_clear_namespace()| ----@note {fn} will receive the keys after mappings have been evaluated function vim.on_key(fn, ns_id) if fn == nil and ns_id == nil then return #on_key_cbs @@ -1049,10 +1049,10 @@ function vim._init_default_mappings() map('i', '<C-W>', '<C-G>u<C-W>') vim.keymap.set('x', '*', function() _visual_search('/') - end, { desc = 'Nvim builtin', silent = true }) + end, { desc = ':help v_star-default', silent = true }) vim.keymap.set('x', '#', function() _visual_search('?') - end, { desc = 'Nvim builtin', silent = true }) + end, { desc = ':help v_#-default', silent = true }) -- Use : instead of <Cmd> so that ranges are supported. #19365 map('n', '&', ':&&<CR>') diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py index 8410a3b5b1..8ad6442f3b 100755 --- a/scripts/gen_vimdoc.py +++ b/scripts/gen_vimdoc.py @@ -585,10 +585,12 @@ def render_node(n, text, prefix='', indent='', width=text_width - indentation, indent=indent, width=width)) i = i + 1 elif n.nodeName == 'simplesect' and 'note' == n.getAttribute('kind'): - text += '\nNote:\n ' + text += ind(' ') for c in n.childNodes: - text += render_node(c, text, indent=' ', width=width) - text += '\n' + if is_blank(render_node(c, text, prefix='• ', indent=' ', width=width)): + continue + text += render_node(c, text, prefix='• ', indent=' ', width=width) + # text += '\n' elif n.nodeName == 'simplesect' and 'warning' == n.getAttribute('kind'): text += 'Warning:\n ' for c in n.childNodes: @@ -620,6 +622,7 @@ def para_as_map(parent, indent='', width=text_width - indentation, fmt_vimhelp=F Keys: 'text': Text from this <para> element + 'note': List of @note strings 'params': <parameterlist> map 'return': List of @return strings 'seealso': List of @see strings @@ -627,6 +630,7 @@ def para_as_map(parent, indent='', width=text_width - indentation, fmt_vimhelp=F """ chunks = { 'text': '', + 'note': [], 'params': collections.OrderedDict(), 'return': [], 'seealso': [], @@ -635,6 +639,7 @@ def para_as_map(parent, indent='', width=text_width - indentation, fmt_vimhelp=F # Ordered dict of ordered lists. groups = collections.OrderedDict([ + ('note', []), ('params', []), ('return', []), ('seealso', []), @@ -645,7 +650,6 @@ def para_as_map(parent, indent='', width=text_width - indentation, fmt_vimhelp=F # nodes to appear together. text = '' kind = '' - last = '' if is_inline(parent): # Flatten inline text from a tree of non-block nodes. text = doc_wrap(render_node(parent, "", fmt_vimhelp=fmt_vimhelp), @@ -658,13 +662,14 @@ def para_as_map(parent, indent='', width=text_width - indentation, fmt_vimhelp=F elif child.nodeName == 'xrefsect': groups['xrefs'].append(child) elif child.nodeName == 'simplesect': - last = kind kind = child.getAttribute('kind') - if kind == 'return' or (kind == 'note' and last == 'return'): + if kind == 'note': + groups['note'].append(child) + elif kind == 'return': groups['return'].append(child) elif kind == 'see': groups['seealso'].append(child) - elif kind in ('note', 'warning'): + elif kind == 'warning': text += render_node(child, text, indent=indent, width=width, fmt_vimhelp=fmt_vimhelp) else: @@ -689,6 +694,9 @@ def para_as_map(parent, indent='', width=text_width - indentation, fmt_vimhelp=F if len(groups['params']) > 0: for child in groups['params']: update_params_map(child, ret_map=chunks['params'], width=width) + for child in groups['note']: + chunks['note'].append(render_node( + child, '', indent=indent, width=width, fmt_vimhelp=fmt_vimhelp).rstrip()) for child in groups['return']: chunks['return'].append(render_node( child, '', indent=indent, width=width, fmt_vimhelp=fmt_vimhelp)) @@ -741,11 +749,15 @@ def fmt_node_as_vimhelp(parent, width=text_width - indentation, indent='', # Generate text from the gathered items. chunks = [para['text']] + if len(para['note']) > 0: + chunks.append('\nNote: ~') + for s in para['note']: + chunks.append(s) if len(para['params']) > 0 and has_nonexcluded_params(para['params']): chunks.append('\nParameters: ~') chunks.append(fmt_param_doc(para['params'])) if len(para['return']) > 0: - chunks.append('\nReturn: ~') + chunks.append('\nReturn (multiple): ~' if len(para['return']) > 1 else '\nReturn: ~') for s in para['return']: chunks.append(s) if len(para['seealso']) > 0: diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index 02b97b0ae1..a0322556b4 100644 --- a/src/nvim/api/buffer.c +++ b/src/nvim/api/buffer.c @@ -1192,8 +1192,9 @@ Boolean nvim_buf_set_mark(Buffer buffer, String name, Integer line, Integer col, return res; } -/// Returns a tuple (row,col) representing the position of the named mark. See -/// |mark-motions|. +/// Returns a `(row,col)` tuple representing the position of the named mark. +/// "End of line" column position is returned as |v:maxcol| (big number). +/// See |mark-motions|. /// /// Marks are (1,0)-indexed. |api-indexing| /// diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 8c40e5ccd7..c15ec4ce53 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -87,6 +87,9 @@ Integer nvim_get_hl_id_by_name(String name) /// Gets all or specific highlight groups in a namespace. /// +/// @note When the `link` attribute is defined in the highlight definition +/// map, other attributes will not be taking effect (see |:hi-link|). +/// /// @param ns_id Get highlight groups for namespace ns_id |nvim_get_namespaces()|. /// Use 0 to get global highlight groups |:highlight|. /// @param opts Options dict: @@ -97,9 +100,6 @@ Integer nvim_get_hl_id_by_name(String name) /// @param[out] err Error details, if any. /// @return Highlight groups as a map from group name to a highlight definition map as in |nvim_set_hl()|, /// or only a single highlight definition map if requested by name or id. -/// -/// @note When the `link` attribute is defined in the highlight definition -/// map, other attributes will not be taking effect (see |:hi-link|). Dictionary nvim_get_hl(Integer ns_id, Dict(get_highlight) *opts, Arena *arena, Error *err) FUNC_API_SINCE(11) { @@ -1958,7 +1958,7 @@ Object nvim__unpack(String str, Error *err) /// Deletes an uppercase/file named mark. See |mark-motions|. /// -/// @note fails with error if a lowercase or buffer local named mark is used. +/// @note Lowercase name (or other buffer-local mark) is an error. /// @param name Mark name /// @return true if the mark was deleted, else false. /// @see |nvim_buf_del_mark()| @@ -1980,12 +1980,13 @@ Boolean nvim_del_mark(String name, Error *err) return res; } -/// Return a tuple (row, col, buffer, buffername) representing the position of -/// the uppercase/file named mark. See |mark-motions|. +/// Returns a `(row, col, buffer, buffername)` tuple representing the position +/// of the uppercase/file named mark. "End of line" column position is returned +/// as |v:maxcol| (big number). See |mark-motions|. /// /// Marks are (1,0)-indexed. |api-indexing| /// -/// @note fails with error if a lowercase or buffer local named mark is used. +/// @note Lowercase name (or other buffer-local mark) is an error. /// @param name Mark name /// @param opts Optional parameters. Reserved for future use. /// @return 4-tuple (row, col, buffer, buffername), (0, 0, 0, '') if the mark is |