From d2e44da516816e2616b531886eb9ba7f4c271fb4 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 6 Jul 2023 22:47:27 +0200 Subject: [PATCH] docs: gather @notes items into one section related: 21eacbfef399 --- runtime/doc/api.txt | 66 +++++++++++++++++--------------------- runtime/doc/diagnostic.txt | 4 +-- runtime/doc/lsp.txt | 5 +-- runtime/doc/lua.txt | 16 ++++----- scripts/gen_vimdoc.py | 26 +++++++++++---- src/nvim/api/vim.c | 2 +- 6 files changed, 61 insertions(+), 58 deletions(-) diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 4f3fc470a9..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,8 +952,8 @@ 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, + Note: ~ + • When the `link` attribute is defined in the highlight definition map, other attributes will not be taking effect (see |:hi-link|). Parameters: ~ @@ -993,8 +993,8 @@ nvim_get_mark({name}, {opts}) *nvim_get_mark()* Marks are (1,0)-indexed. |api-indexing| - Note: - Lowercase name (or other buffer-local mark) is an error. + Note: ~ + • Lowercase name (or other buffer-local mark) is an error. Parameters: ~ • {name} Mark name @@ -1075,12 +1075,10 @@ nvim_input({keys}) *nvim_input()* On execution error: does not fail, but updates v:errmsg. - Note: - |keycodes| like are translated, so "<" is special. To input a + Note: ~ + • |keycodes| like are translated, so "<" is special. To input a literal "<", send . - - Note: - For mouse events use |nvim_input_mouse()|. The pseudokey form + • For mouse events use |nvim_input_mouse()|. The pseudokey form "" is deprecated since |api-level| 6. Attributes: ~ @@ -1100,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 ("") of @@ -1317,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: ~ @@ -1410,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()|. @@ -2141,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: ~ @@ -2325,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: ~ @@ -2388,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 @@ -3444,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 5fd06b3a14..7bec93de89 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -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: ~ diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 7bc5b4a29b..9e4815bea5 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -1475,14 +1475,10 @@ 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 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 + 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} fun(key: string) Function invoked on every key press. @@ -2912,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/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py index eea56840ef..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 element + 'note': List of @note strings 'params': 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,6 +749,10 @@ 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'])) diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 13021f9c57..c15ec4ce53 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -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()|