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`.

1 files changed, 5 insertions, 5 deletions

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()|