docs: gather @notes items into one section

related: 21eacbfef399

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 <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: ~
@@ -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 ("<LeftMouse><col,row>") 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 <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,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()|