docs: "Return (multiple)" heading

Problem:
Lua functions that return multiple results are declared by using
multiple `@return` docstring directives. But the generated docs don't
make it obvious what this represents.

Solution:
- Generate a "Return (multiple)" heading for multiple-value functions.
- Fix `@note` directives randomly placed after `@return`.

6 files changed, 16 insertions, 16 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index c0e6dbc015..4f3fc470a9 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -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
 
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index b21c1d6e9d..5fd06b3a14 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.
@@ -1623,7 +1623,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 +1833,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 +1857,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 +2091,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 f33bd3eb5c..7bc5b4a29b 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2364,7 +2364,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
 
@@ -2567,7 +2567,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
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/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py
index 8410a3b5b1..eea56840ef 100755
--- a/scripts/gen_vimdoc.py
+++ b/scripts/gen_vimdoc.py
@@ -745,7 +745,7 @@ def fmt_node_as_vimhelp(parent, width=text_width - indentation, indent='',
             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/vim.c b/src/nvim/api/vim.c
index 3ffaaab780..13021f9c57 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)
 {