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, 4 insertions, 4 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