commit 3a721820c39b7524a2e6d6a73774498104a38962
parent 00d2f4b96eb9c8dcb6b9f67e256bb7faa19354db
Author: Justin M. Keyes <justinkz@gmail.com>
Date: Thu, 6 Jul 2023 15:32:39 +0200
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`.
Diffstat:
6 files changed, 16 insertions(+), 16 deletions(-)
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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)
{
