From 766f4978d6cb146511cf0b676c01e5327db46647 Mon Sep 17 00:00:00 2001
From: Raphael <glepnir@neovim.pro>
Date: Mon, 10 Jul 2023 19:38:15 +0800
Subject: [PATCH] fix(lint): lint warnings #24226

---
 runtime/doc/lsp.txt              | 17 ++++++++---------
 runtime/doc/lua.txt              |  6 +++---
 runtime/lua/vim/_editor.lua      |  2 +-
 runtime/lua/vim/_watch.lua       |  4 ++--
 runtime/lua/vim/filetype.lua     |  2 +-
 runtime/lua/vim/fs.lua           |  8 ++++----
 runtime/lua/vim/lsp.lua          | 20 ++++++++++----------
 runtime/lua/vim/lsp/buf.lua      | 15 ++++++++-------
 runtime/lua/vim/lsp/handlers.lua |  7 ++++---
 runtime/lua/vim/lsp/log.lua      |  2 +-
 runtime/lua/vim/lsp/rpc.lua      | 17 ++++++++---------
 runtime/lua/vim/lsp/sync.lua     | 12 +++++++-----
 runtime/lua/vim/uri.lua          | 10 ++--------
 13 files changed, 59 insertions(+), 63 deletions(-)

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 7bec93de89..4bafb622a6 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -663,7 +663,7 @@ buf_request_all({bufnr}, {method}, {params}, {handler})
                    Server results are passed as a `client_id:result` map.
 
     Return: ~
-        fun() cancel Function that cancels all requests.
+        (function) cancel Function that cancels all requests.
 
                                                   *vim.lsp.buf_request_sync()*
 buf_request_sync({bufnr}, {method}, {params}, {timeout_ms})
@@ -802,7 +802,7 @@ get_client_by_id({client_id})                     *vim.lsp.get_client_by_id()*
       • {client_id}  (integer) client id
 
     Return: ~
-        |vim.lsp.client| object, or nil
+        (nil|lsp.Client) client rpc object
 
 get_log_path()                                        *vim.lsp.get_log_path()*
     Gets the path of the logfile used by the LSP client.
@@ -825,7 +825,7 @@ omnifunc({findstart}, {base})                             *vim.lsp.omnifunc()*
       • {base}       (integer) findstart=0, text to match against
 
     Return: ~
-        (integer) Decided by {findstart}:
+        integer|table Decided by {findstart}:
         • findstart=0: column where the completion starts, or -2 or -3
         • findstart=1: list of matches (actually just calls |complete()|)
 
@@ -1116,7 +1116,7 @@ completion({context})                               *vim.lsp.buf.completion()*
     called in Insert mode.
 
     Parameters: ~
-      • {context}  (context support not yet implemented) Additional
+      • {context}  (table) (context support not yet implemented) Additional
                    information about the context in which a completion was
                    triggered (how it was triggered, and by which trigger
                    character, if applicable)
@@ -1296,7 +1296,7 @@ workspace_symbol({query}, {options})          *vim.lsp.buf.workspace_symbol()*
     string means no filtering is done.
 
     Parameters: ~
-      • {query}    (string, optional)
+      • {query}    (string|nil) optional
       • {options}  (table|nil) additional options
                    • on_list: (function) handler for list results. See
                      |lsp-on-list-handler|
@@ -2040,7 +2040,7 @@ notify({method}, {params})                              *vim.lsp.rpc.notify()*
       • {params}  (table|nil) Parameters for the invoked LSP method
 
     Return: ~
-        (bool) `true` if notification could be sent, `false` if not
+        (boolean) `true` if notification could be sent, `false` if not
 
                                                        *vim.lsp.rpc.request()*
 request({method}, {params}, {callback}, {notify_reply_callback})
@@ -2092,9 +2092,8 @@ start({cmd}, {cmd_args}, {dispatchers}, {extra_spawn_params})
                               • {env} (table) Additional environment variables
                                 for LSP server process
 
-    Return (multiple): ~
-        Client RPC object.
-        Methods:
+    Return: ~
+        (table|nil) Client RPC object, with these methods:
         • `notify()` |vim.lsp.rpc.notify()|
         • `request()` |vim.lsp.rpc.request()|
         • `is_closing()` returns a boolean indicating if the RPC is closing.
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 9e4815bea5..ae3c248d64 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1518,7 +1518,7 @@ paste({lines}, {phase})                                          *vim.paste()*
                  • 3: ends the paste (exactly once)
 
     Return: ~
-        (boolean) # false if client should cancel the paste.
+        (boolean) result false if client should cancel the paste.
 
     See also: ~
       • |paste| @alias paste_phase -1 | 1 | 2 | 3
@@ -2637,7 +2637,7 @@ basename({file})                                           *vim.fs.basename()*
       • {file}  (string) File or directory
 
     Return: ~
-        (string) Basename of {file}
+        (string|nil) Basename of {file}
 
 dir({path}, {opts})                                             *vim.fs.dir()*
     Return an iterator over the files and directories located in {path}
@@ -2664,7 +2664,7 @@ dirname({file})                                             *vim.fs.dirname()*
       • {file}  (string) File or directory
 
     Return: ~
-        (string) Parent directory of {file}
+        (string|nil) Parent directory of {file}
 
 find({names}, {opts})                                          *vim.fs.find()*
     Find files or directories in the given path.
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index 5a93f5cd60..47215416e0 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -219,7 +219,7 @@ do
   ---                - 1: starts the paste (exactly once)
   ---                - 2: continues the paste (zero or more times)
   ---                - 3: ends the paste (exactly once)
-  ---@returns boolean # false if client should cancel the paste.
+  ---@return boolean result false if client should cancel the paste.
   function vim.paste(lines, phase)
     local now = vim.uv.now()
     local is_first_chunk = phase < 2
diff --git a/runtime/lua/vim/_watch.lua b/runtime/lua/vim/_watch.lua
index d489cef9fc..00b7416098 100644
--- a/runtime/lua/vim/_watch.lua
+++ b/runtime/lua/vim/_watch.lua
@@ -37,7 +37,7 @@ end
 ---     - uvflags (table|nil)
 ---                Same flags as accepted by |uv.fs_event_start()|
 ---@param callback (function) The function called when new events
----@return (function) A function to stop the watch
+---@return (function) Stops the watcher
 function M.watch(path, opts, callback)
   vim.validate({
     path = { path, 'string', false },
@@ -208,7 +208,7 @@ end
 ---                not match the pattern will be reported. Matches against both files and
 ---                directories. When nil, matches nothing.
 ---@param callback (function) The function called when new events
----@returns (function) A function to stop the watch.
+---@return function Stops the watcher
 function M.poll(path, opts, callback)
   vim.validate({
     path = { path, 'string', false },
diff --git a/runtime/lua/vim/filetype.lua b/runtime/lua/vim/filetype.lua
index bc880ed130..33d451315d 100644
--- a/runtime/lua/vim/filetype.lua
+++ b/runtime/lua/vim/filetype.lua
@@ -28,7 +28,7 @@ end
 --- If only start_lnum is specified, return a single line as a string.
 --- If both start_lnum and end_lnum are omitted, return all lines from the buffer.
 ---
----@param bufnr integer|nil The buffer to get the lines from
+---@param bufnr integer The buffer to get the lines from
 ---@param start_lnum integer|nil The line number of the first line (inclusive, 1-based)
 ---@param end_lnum integer|nil The line number of the last line (inclusive, 1-based)
 ---@return table<string>|string Array of lines, or string when end_lnum is omitted
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
index cdb314fa3d..48d76e5d7e 100644
--- a/runtime/lua/vim/fs.lua
+++ b/runtime/lua/vim/fs.lua
@@ -20,7 +20,7 @@ local iswin = vim.uv.os_uname().sysname == 'Windows_NT'
 --- </pre>
 ---
 ---@param start (string) Initial file or directory.
----@return (function) Iterator
+---@return function Iterator
 function M.parents(start)
   return function(_, dir)
     local parent = M.dirname(dir)
@@ -37,7 +37,7 @@ end
 --- Return the parent directory of the given file or directory
 ---
 ---@param file (string) File or directory
----@return (string) Parent directory of {file}
+---@return string|nil Parent directory of {file}
 function M.dirname(file)
   if file == nil then
     return nil
@@ -59,8 +59,8 @@ end
 
 --- Return the basename of the given file or directory
 ---
----@param file (string) File or directory
----@return (string) Basename of {file}
+---@param file string File or directory
+---@return string|nil Basename of {file}
 function M.basename(file)
   if file == nil then
     return nil
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
index ca4851f8d7..ed431e080e 100644
--- a/runtime/lua/vim/lsp.lua
+++ b/runtime/lua/vim/lsp.lua
@@ -1951,7 +1951,7 @@ end
 ---
 ---@param client_id integer client id
 ---
----@returns |vim.lsp.client| object, or nil
+---@return (nil|lsp.Client) client rpc object
 function lsp.get_client_by_id(client_id)
   return active_clients[client_id] or uninitialized_clients[client_id]
 end
@@ -2090,13 +2090,14 @@ api.nvim_create_autocmd('VimLeavePre', {
 ---@param bufnr (integer) Buffer handle, or 0 for current.
 ---@param method (string) LSP method name
 ---@param params table|nil Parameters to send to the server
----@param handler lsp-handler|nil See |lsp-handler|
+---@param handler lsp-handler See |lsp-handler|
 ---       If nil, follows resolution strategy defined in |lsp-handler-configuration|
 ---
----@return table<integer, integer>, fun() 2-tuple:
----  - Map of client-id:request-id pairs for all successful requests.
----  - Function which can be used to cancel all the requests. You could instead
----    iterate all clients and call their `cancel_request()` methods.
+---@return table<integer, integer> client_request_ids Map of client-id:request-id pairs
+---for all successful requests.
+---@return function _cancel_all_requests Function which can be used to
+---cancel all the requests. You could instead
+---iterate all clients and call their `cancel_request()` methods.
 function lsp.buf_request(bufnr, method, params, handler)
   validate({
     bufnr = { bufnr, 'n', true },
@@ -2147,8 +2148,7 @@ end
 ---@param handler fun(results: table<integer, {error: lsp.ResponseError, result: any}>) (function)
 --- Handler called after all requests are completed. Server results are passed as
 --- a `client_id:result` map.
----
----@return fun() cancel Function that cancels all requests.
+---@return function cancel Function that cancels all requests.
 function lsp.buf_request_all(bufnr, method, params, handler)
   local results = {}
   local result_count = 0
@@ -2257,7 +2257,7 @@ end
 ---@param findstart integer 0 or 1, decides behavior
 ---@param base integer findstart=0, text to match against
 ---
----@returns (integer) Decided by {findstart}:
+---@return integer|table Decided by {findstart}:
 --- - findstart=0: column where the completion starts, or -2 or -3
 --- - findstart=1: list of matches (actually just calls |complete()|)
 function lsp.omnifunc(findstart, base)
@@ -2405,7 +2405,7 @@ end
 --- is a |vim.lsp.client| object.
 ---
 ---@param bufnr (integer|nil): Buffer handle, or 0 for current
----@returns (table) Table of (client_id, client) pairs
+---@return table result is table of (client_id, client) pairs
 ---@deprecated Use |vim.lsp.get_active_clients()| instead.
 function lsp.buf_get_clients(bufnr)
   local result = {}
diff --git a/runtime/lua/vim/lsp/buf.lua b/runtime/lua/vim/lsp/buf.lua
index bac66b671d..8ae0e0cde3 100644
--- a/runtime/lua/vim/lsp/buf.lua
+++ b/runtime/lua/vim/lsp/buf.lua
@@ -13,10 +13,11 @@ local M = {}
 ---@param params (table|nil) Parameters to send to the server
 ---@param handler (function|nil) See |lsp-handler|. Follows |lsp-handler-resolution|
 --
----@returns 2-tuple:
----  - Map of client-id:request-id pairs for all successful requests.
----  - Function which can be used to cancel all the requests. You could instead
----    iterate all clients and call their `cancel_request()` methods.
+---@return table<integer, integer> client_request_ids Map of client-id:request-id pairs
+---for all successful requests.
+---@return function _cancel_all_requests Function which can be used to
+---cancel all the requests. You could instead
+---iterate all clients and call their `cancel_request()` methods.
 ---
 ---@see |vim.lsp.buf_request()|
 local function request(method, params, handler)
@@ -30,7 +31,7 @@ end
 --- Checks whether the language servers attached to the current buffer are
 --- ready.
 ---
----@returns `true` if server responds.
+---@return boolean if server responds.
 ---@deprecated
 function M.server_ready()
   vim.deprecate('vim.lsp.buf.server_ready', nil, '0.10.0')
@@ -108,7 +109,7 @@ end
 --- Retrieves the completion items at the current cursor position. Can only be
 --- called in Insert mode.
 ---
----@param context (context support not yet implemented) Additional information
+---@param context table (context support not yet implemented) Additional information
 --- about the context in which a completion was triggered (how it was triggered,
 --- and by which trigger character, if applicable)
 ---
@@ -549,7 +550,7 @@ end
 --- call, the user is prompted to enter a string on the command line. An empty
 --- string means no filtering is done.
 ---
----@param query (string, optional)
+---@param query string|nil optional
 ---@param options table|nil additional options
 ---     - on_list: (function) handler for list results. See |lsp-on-list-handler|
 function M.workspace_symbol(query, options)
diff --git a/runtime/lua/vim/lsp/handlers.lua b/runtime/lua/vim/lsp/handlers.lua
index 70781cb7a6..20c4d7458b 100644
--- a/runtime/lua/vim/lsp/handlers.lua
+++ b/runtime/lua/vim/lsp/handlers.lua
@@ -382,7 +382,7 @@ M['textDocument/hover'] = M.hover
 
 ---@private
 --- Jumps to a location. Used as a handler for multiple LSP methods.
----@param _ (not used)
+---@param _ nil not used
 ---@param result (table) result of LSP method; a location or a list of locations.
 ---@param ctx (table) table containing the context of the request, including the method
 ---(`textDocument/definition` can return `Location` or `Location[]`
@@ -496,8 +496,9 @@ end
 --- Displays call hierarchy in the quickfix window.
 ---
 ---@param direction `"from"` for incoming calls and `"to"` for outgoing calls
----@returns `CallHierarchyIncomingCall[]` if {direction} is `"from"`,
----@returns `CallHierarchyOutgoingCall[]` if {direction} is `"to"`,
+---@return function
+--- `CallHierarchyIncomingCall[]` if {direction} is `"from"`,
+--- `CallHierarchyOutgoingCall[]` if {direction} is `"to"`,
 local make_call_hierarchy_handler = function(direction)
   return function(_, result)
     if not result then
diff --git a/runtime/lua/vim/lsp/log.lua b/runtime/lua/vim/lsp/log.lua
index c77e7c045b..033f93bd6e 100644
--- a/runtime/lua/vim/lsp/log.lua
+++ b/runtime/lua/vim/lsp/log.lua
@@ -44,7 +44,7 @@ do
   vim.fn.mkdir(vim.fn.stdpath('log'), 'p')
 
   --- Returns the log filename.
-  ---@returns (string) log filename
+  ---@return string log filename
   function log.get_filename()
     return logfilename
   end
diff --git a/runtime/lua/vim/lsp/rpc.lua b/runtime/lua/vim/lsp/rpc.lua
index 6552eaa800..c110c3a67c 100644
--- a/runtime/lua/vim/lsp/rpc.lua
+++ b/runtime/lua/vim/lsp/rpc.lua
@@ -8,7 +8,7 @@ local is_win = uv.os_uname().version:find('Windows')
 ---@private
 --- Checks whether a given path exists and is a directory.
 ---@param filename (string) path to check
----@returns (bool)
+---@return boolean
 local function is_dir(filename)
   local stat = uv.fs_stat(filename)
   return stat and stat.type == 'directory' or false
@@ -18,7 +18,7 @@ end
 --- Embeds the given string into a table and correctly computes `Content-Length`.
 ---
 ---@param encoded_message (string)
----@returns (table) table containing encoded message and `Content-Length` attribute
+---@return string containing encoded message and `Content-Length` attribute
 local function format_message_with_content_length(encoded_message)
   return table.concat({
     'Content-Length: ',
@@ -32,7 +32,7 @@ end
 --- Parses an LSP Message's header
 ---
 ---@param header string: The header to parse.
----@return table parsed headers
+---@return table # parsed headers
 local function parse_headers(header)
   assert(type(header) == 'string', 'header must be a string')
   local headers = {}
@@ -190,7 +190,8 @@ end
 ---
 ---@param method (string) The invoked LSP method
 ---@param params (table): Parameters for the invoked LSP method
----@returns `nil` and `vim.lsp.protocol.ErrorCodes.MethodNotFound`.
+---@return nil
+---@return table `vim.lsp.protocol.ErrorCodes.MethodNotFound`
 function default_dispatchers.server_request(method, params)
   local _ = log.debug() and log.debug('server_request', method, params)
   return nil, rpc_response_error(protocol.ErrorCodes.MethodNotFound)
@@ -268,7 +269,7 @@ end
 --- Sends a notification to the LSP server.
 ---@param method (string) The invoked LSP method
 ---@param params (any): Parameters for the invoked LSP method
----@returns (bool) `true` if notification could be sent, `false` if not
+---@return boolean `true` if notification could be sent, `false` if not
 function Client:notify(method, params)
   return self:encode_and_send({
     jsonrpc = '2.0',
@@ -522,7 +523,7 @@ local function public_client(client)
   --- Sends a notification to the LSP server.
   ---@param method (string) The invoked LSP method
   ---@param params (table|nil): Parameters for the invoked LSP method
-  ---@returns (bool) `true` if notification could be sent, `false` if not
+  ---@return boolean `true` if notification could be sent, `false` if not
   function result.notify(method, params)
     return client:notify(method, params)
   end
@@ -624,9 +625,7 @@ end
 --- server process. May contain:
 --- - {cwd} (string) Working directory for the LSP server process
 --- - {env} (table) Additional environment variables for LSP server process
----@returns Client RPC object.
----
----@returns Methods:
+---@return table|nil Client RPC object, with these methods:
 --- - `notify()` |vim.lsp.rpc.notify()|
 --- - `request()` |vim.lsp.rpc.request()|
 --- - `is_closing()` returns a boolean indicating if the RPC is closing.
diff --git a/runtime/lua/vim/lsp/sync.lua b/runtime/lua/vim/lsp/sync.lua
index fb5b0b3194..350c096b47 100644
--- a/runtime/lua/vim/lsp/sync.lua
+++ b/runtime/lua/vim/lsp/sync.lua
@@ -94,7 +94,8 @@ end
 ---@param line string the line to index into
 ---@param byte integer the byte idx
 ---@param offset_encoding string utf-8|utf-16|utf-32|nil (default: utf-8)
----@returns table<string, int> byte_idx and char_idx of first change position
+---@return integer byte_idx of first change position
+---@return integer char_idx of first change position
 local function align_end_position(line, byte, offset_encoding)
   local char
   -- If on the first byte, or an empty string: the trivial case
@@ -129,7 +130,7 @@ end
 ---@param lastline integer lastline from on_lines, adjusted to 1-index
 ---@param new_lastline integer new_lastline from on_lines, adjusted to 1-index
 ---@param offset_encoding string utf-8|utf-16|utf-32|nil (fallback to utf-8)
----@returns table<int, int> line_idx, byte_idx, and char_idx of first change position
+---@return table result table include line_idx, byte_idx, and char_idx of first change position
 local function compute_start_range(
   prev_lines,
   curr_lines,
@@ -209,7 +210,8 @@ end
 ---@param lastline integer
 ---@param new_lastline integer
 ---@param offset_encoding string
----@returns (int, int) end_line_idx and end_col_idx of range
+---@return integer|table end_line_idx and end_col_idx of range
+---@return table|nil end_col_idx of range
 local function compute_end_range(
   prev_lines,
   curr_lines,
@@ -310,7 +312,7 @@ end
 ---@param lines table list of lines
 ---@param start_range table table returned by first_difference
 ---@param end_range table new_end_range returned by last_difference
----@returns string text extracted from defined region
+---@return string text extracted from defined region
 local function extract_text(lines, start_range, end_range, line_ending)
   if not lines[start_range.line_idx] then
     return ''
@@ -392,7 +394,7 @@ end
 ---@param lastline integer line to begin search in old_lines for last difference
 ---@param new_lastline integer line to begin search in new_lines for last difference
 ---@param offset_encoding string encoding requested by language server
----@returns table TextDocumentContentChangeEvent see https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocumentContentChangeEvent
+---@return table TextDocumentContentChangeEvent see https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocumentContentChangeEvent
 function M.compute_diff(
   prev_lines,
   curr_lines,
diff --git a/runtime/lua/vim/uri.lua b/runtime/lua/vim/uri.lua
index 08ed829114..dec7840eb0 100644
--- a/runtime/lua/vim/uri.lua
+++ b/runtime/lua/vim/uri.lua
@@ -30,14 +30,8 @@ do
     -- https://tools.ietf.org/html/rfc3986#section-2.2
     rfc3986 = "^A-Za-z0-9%-._~!$&'()*+,;=:@/",
   }
-  local sbyte, tohex = string.byte
-  if jit then
-    tohex = require('bit').tohex
-  else
-    tohex = function(b)
-      return string.format('%02x', b)
-    end
-  end
+  local sbyte = string.byte
+  local tohex = require('bit').tohex
 
   ---@private
   local function percent_encode_char(char)