docs: make Lua docstrings consistent #15255

The official developer documentation in in :h dev-lua-doc specifies to
use "--@" for special/magic tokens. However, this format is not
consistent with EmmyLua notation (used by some Lua language servers) nor
with the C version of the magic docstring tokens which use three comment
characters.

Further, the code base is currently split between usage of "--@",
"---@", and "--- @". In an effort to remain consistent, change all Lua
magic tokens to use "---@" and update the developer documentation
accordingly.

24 files changed, 689 insertions, 687 deletions

diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index becfb1715f..60a3f870a9 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -191,8 +191,8 @@ definitions.  The |lua-vim| :help is generated from the docstrings.
 
 Docstring format:
 - Lines in the main description start with `---`
-- Special tokens start with `--@` followed by the token name:
-  `--@see`, `--@param`, `--@returns`
+- Special tokens start with `---@` followed by the token name:
+  `---@see`, `---@param`, `---@returns`
 - Limited markdown is supported.
   - List-items start with `-` (useful to nest or "indent")
 - Use `<pre>`  for code samples.
@@ -211,11 +211,11 @@ vim.paste in src/nvim/lua/vim.lua like this: >
     --- end)()
     --- </pre>
     ---
-    --@see |paste|
+    ---@see |paste|
     ---
-    --@param lines  ...
-    --@param phase  ...
-    --@returns false if client should cancel the paste.
+    ---@param lines  ...
+    ---@param phase  ...
+    ---@returns false if client should cancel the paste.
 
 
 LUA							*dev-lua*
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 4d32be97d3..b04d9c267a 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -1510,11 +1510,6 @@ reset({client_id}, {buffer_client_map})           *vim.lsp.diagnostic.reset()*
                     {buffer_client_map}  table map of buffers to active
                                          clients
 
-                                       *vim.lsp.diagnostic.restore_extmarks()*
-restore_extmarks({bufnr}, {last})
-                Parameters: ~
-                    {last}  number last line that was changed
-
 save({diagnostics}, {bufnr}, {client_id})          *vim.lsp.diagnostic.save()*
                 Save diagnostics to the current buffer.
 
@@ -1526,10 +1521,6 @@ save({diagnostics}, {bufnr}, {client_id})          *vim.lsp.diagnostic.save()*
                     {bufnr}        number
                     {client_id}    number
 
-                                          *vim.lsp.diagnostic.save_extmarks()*
-save_extmarks({bufnr}, {client_id})
-                TODO: Documentation
-
 set_loclist({opts})                         *vim.lsp.diagnostic.set_loclist()*
                 Sets the location list
 
@@ -1966,7 +1957,9 @@ diagnostics_to_items({diagnostics_by_bufnr}, {predicate})
                 Parameters: ~
                     {diagnostics_by_bufnr}  table bufnr -> Diagnostic []
                     {predicate}             an optional function to filter the
-                                            diagnostics.
+                                            diagnostics. If present, only
+                                            diagnostic items matching will be
+                                            included.
 
                 Return: ~
                     table (A list of items)
@@ -1999,6 +1992,8 @@ get_effective_tabstop({bufnr})          *vim.lsp.util.get_effective_tabstop()*
                     |softtabstop|
 
 get_line({uri}, {row})                               *vim.lsp.util.get_line()*
+                Gets the zero-indexed line from the given uri.
+
                 Parameters: ~
                     {uri}  string uri of the resource to get the line from
                     {row}  number zero-indexed line number
@@ -2007,6 +2002,8 @@ get_line({uri}, {row})                               *vim.lsp.util.get_line()*
                     string the line at row in filename
 
 get_lines({uri}, {rows})                            *vim.lsp.util.get_lines()*
+                Gets the zero-indexed lines from the given uri.
+
                 Parameters: ~
                     {uri}   string uri of the resource to get the lines from
                     {rows}  number[] zero-indexed line numbers
@@ -2014,9 +2011,6 @@ get_lines({uri}, {rows})                            *vim.lsp.util.get_lines()*
                 Return: ~
                     table<number string> a table mapping rows to lines
 
-get_markdown_fences()                     *vim.lsp.util.get_markdown_fences()*
-                TODO: Documentation
-
 get_progress_messages()                 *vim.lsp.util.get_progress_messages()*
                 TODO: Documentation
 
@@ -2197,6 +2191,8 @@ preview_location({location}, {opts})         *vim.lsp.util.preview_location()*
                     or nil
 
 rename({old_fname}, {new_fname}, {opts})               *vim.lsp.util.rename()*
+                Rename old_fname to new_fname
+
                 Parameters: ~
                     {opts}  (table)
 
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 749ce3622e..28667d5bd1 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1177,7 +1177,9 @@ make_dict_accessor({scope})                         *vim.make_dict_accessor()*
                 TODO: Documentation
 
 notify({msg}, {log_level}, {_opts})                             *vim.notify()*
-                Notification provider without a runtime, writes to :Messages
+                Notification provider
+
+                Without a runtime, writes to :Messages
 
                 Parameters: ~
                     {msg}        Content of the notification to show to the
@@ -1186,6 +1188,9 @@ notify({msg}, {log_level}, {_opts})                             *vim.notify()*
                     {opts}       Dictionary with optional options (timeout,
                                  etc)
 
+                See also: ~
+                    :help nvim_notify
+
 paste({lines}, {phase})                                          *vim.paste()*
                 Paste handler, invoked by |nvim_paste()| when a conforming UI
                 (such as the |TUI|) pastes text into the editor.
diff --git a/runtime/lua/vim/F.lua b/runtime/lua/vim/F.lua
index 7925ff6e44..09467eb8c6 100644
--- a/runtime/lua/vim/F.lua
+++ b/runtime/lua/vim/F.lua
@@ -2,8 +2,8 @@ local F = {}
 
 --- Returns {a} if it is not nil, otherwise returns {b}.
 ---
---@param a
---@param b
+---@param a
+---@param b
 function F.if_nil(a, b)
   if a == nil then return b end
   return a
diff --git a/runtime/lua/vim/highlight.lua b/runtime/lua/vim/highlight.lua
index 0012dce081..4cb1994419 100644
--- a/runtime/lua/vim/highlight.lua
+++ b/runtime/lua/vim/highlight.lua
@@ -2,7 +2,7 @@ local api = vim.api
 
 local highlight = {}
 
---@private
+---@private
 function highlight.create(higroup, hi_info, default)
   local options = {}
   -- TODO: Add validation
@@ -12,7 +12,7 @@ function highlight.create(higroup, hi_info, default)
   vim.cmd(string.format([[highlight %s %s %s]], default and "default" or "", higroup, table.concat(options, " ")))
 end
 
---@private
+---@private
 function highlight.link(higroup, link_to, force)
   vim.cmd(string.format([[highlight%s link %s %s]], force and "!" or " default", higroup, link_to))
 end
@@ -20,11 +20,11 @@ end
 
 --- Highlight range between two positions
 ---
---@param bufnr number of buffer to apply highlighting to
---@param ns namespace to add highlight to
---@param higroup highlight group to use for highlighting
---@param rtype type of range (:help setreg, default charwise)
---@param inclusive boolean indicating whether the range is end-inclusive (default false)
+---@param bufnr number of buffer to apply highlighting to
+---@param ns namespace to add highlight to
+---@param higroup highlight group to use for highlighting
+---@param rtype type of range (:help setreg, default charwise)
+---@param inclusive boolean indicating whether the range is end-inclusive (default false)
 function highlight.range(bufnr, ns, higroup, start, finish, rtype, inclusive)
   rtype = rtype or 'v'
   inclusive = inclusive or false
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
index ca8db73d43..df48c10881 100644
--- a/runtime/lua/vim/lsp.lua
+++ b/runtime/lua/vim/lsp.lua
@@ -55,21 +55,21 @@ lsp._request_name_to_capability = {
 
 -- TODO improve handling of scratch buffers with LSP attached.
 
---@private
+---@private
 --- Concatenates and writes a list of strings to the Vim error buffer.
 ---
---@param {...} (List of strings) List to write to the buffer
+---@param {...} (List of strings) List to write to the buffer
 local function err_message(...)
   nvim_err_writeln(table.concat(vim.tbl_flatten{...}))
   nvim_command("redraw")
 end
 
---@private
+---@private
 --- Returns the buffer number for the given {bufnr}.
 ---
---@param bufnr (number) Buffer number to resolve. Defaults to the current
+---@param bufnr (number) Buffer number to resolve. Defaults to the current
 ---buffer if not given.
---@returns bufnr (number) Number of requested buffer
+---@returns bufnr (number) Number of requested buffer
 local function resolve_bufnr(bufnr)
   validate { bufnr = { bufnr, 'n', true } }
   if bufnr == nil or bufnr == 0 then
@@ -78,21 +78,21 @@ local function resolve_bufnr(bufnr)
   return bufnr
 end
 
---@private
+---@private
 --- Called by the client when trying to call a method that's not
 --- supported in any of the servers registered for the current buffer.
---@param method (string) name of the method
+---@param method (string) name of the method
 function lsp._unsupported_method(method)
   local msg = string.format("method %s is not supported by any of the servers registered for the current buffer", method)
   log.warn(msg)
   return lsp.rpc_response_error(protocol.ErrorCodes.MethodNotFound, msg)
 end
 
---@private
+---@private
 --- Checks whether a given path is a directory.
 ---
---@param filename (string) path to check
---@returns true if {filename} exists and is a directory, false otherwise
+---@param filename (string) path to check
+---@returns true if {filename} exists and is a directory, false otherwise
 local function is_dir(filename)
   validate{filename={filename,'s'}}
   local stat = uv.fs_stat(filename)
@@ -108,10 +108,10 @@ local valid_encodings = {
 }
 
 local client_index = 0
---@private
+---@private
 --- Returns a new, unused client id.
 ---
---@returns (number) client id
+---@returns (number) client id
 local function next_client_id()
   client_index = client_index + 1
   return client_index
@@ -124,11 +124,11 @@ local uninitialized_clients = {}
 -- Tracks all buffers attached to a client.
 local all_client_active_buffers = {}
 
---@private
+---@private
 --- Invokes a function for each LSP client attached to the buffer {bufnr}.
 ---
---@param bufnr (Number) of buffer
---@param fn (function({client}, {client_id}, {bufnr}) Function to run on
+---@param bufnr (Number) of buffer
+---@param fn (function({client}, {client_id}, {bufnr}) Function to run on
 ---each client attached to that buffer.
 local function for_each_buffer_client(bufnr, fn)
   validate {
@@ -154,11 +154,11 @@ lsp.client_errors = tbl_extend("error", lsp_rpc.client_errors, vim.tbl_add_rever
   ON_INIT_CALLBACK_ERROR = table.maxn(lsp_rpc.client_errors) + 1;
 })
 
---@private
+---@private
 --- Normalizes {encoding} to valid LSP encoding names.
 ---
---@param encoding (string) Encoding to normalize
---@returns (string) normalized encoding name
+---@param encoding (string) Encoding to normalize
+---@returns (string) normalized encoding name
 local function validate_encoding(encoding)
   validate {
     encoding = { encoding, 's' };
@@ -167,13 +167,13 @@ local function validate_encoding(encoding)
       or error(string.format("Invalid offset encoding %q. Must be one of: 'utf-8', 'utf-16', 'utf-32'", encoding))
 end
 
---@internal
+---@internal
 --- Parses a command invocation into the command itself and its args. If there
 --- are no arguments, an empty table is returned as the second argument.
 ---
---@param input (List)
---@returns (string) the command
---@returns (list of strings) its arguments
+---@param input (List)
+---@returns (string) the command
+---@returns (list of strings) its arguments
 function lsp._cmd_parts(input)
   vim.validate{cmd={
     input,
@@ -192,12 +192,12 @@ function lsp._cmd_parts(input)
   return cmd, cmd_args
 end
 
---@private
+---@private
 --- Augments a validator function with support for optional (nil) values.
 ---
---@param fn (function(v)) The original validator function; should return a
+---@param fn (function(v)) The original validator function; should return a
 ---bool.
---@returns (function(v)) The augmented function. Also returns true if {v} is
+---@returns (function(v)) The augmented function. Also returns true if {v} is
 ---`nil`.
 local function optional_validator(fn)
   return function(v)
@@ -205,14 +205,14 @@ local function optional_validator(fn)
   end
 end
 
---@private
+---@private
 --- Validates a client configuration as given to |vim.lsp.start_client()|.
 ---
---@param config (table)
---@returns (table) "Cleaned" config, containing only the command, its
+---@param config (table)
+---@returns (table) "Cleaned" config, containing only the command, its
 ---arguments, and a valid encoding.
 ---
---@see |vim.lsp.start_client()|
+---@see |vim.lsp.start_client()|
 local function validate_client_config(config)
   validate {
     config = { config, 't' };
@@ -253,11 +253,11 @@ local function validate_client_config(config)
   }
 end
 
---@private
+---@private
 --- Returns full text of buffer {bufnr} as a string.
 ---
---@param bufnr (number) Buffer handle, or 0 for current.
---@returns Buffer text as string.
+---@param bufnr (number) Buffer handle, or 0 for current.
+---@returns Buffer text as string.
 local function buf_get_full_text(bufnr)
   local text = table.concat(nvim_buf_get_lines(bufnr, 0, -1, true), '\n')
   if nvim_buf_get_option(bufnr, 'eol') then
@@ -266,14 +266,14 @@ local function buf_get_full_text(bufnr)
   return text
 end
 
---@private
+---@private
 --- Memoizes a function. On first run, the function return value is saved and
 --- immediately returned on subsequent runs. If the function returns a multival,
 --- only the first returned value will be memoized and returned. The function will only be run once,
 --- even if it has side-effects.
 ---
---@param fn (function) Function to run
---@returns (function) Memoized function
+---@param fn (function) Function to run
+---@returns (function) Memoized function
 local function once(fn)
   local value
   local ran = false
@@ -426,11 +426,11 @@ do
 end
 
 
---@private
+---@private
 --- Default handler for the 'textDocument/didOpen' LSP notification.
 ---
---@param bufnr (Number) Number of the buffer, or 0 for current
---@param client Client object
+---@param bufnr (Number) Number of the buffer, or 0 for current
+---@param client Client object
 local function text_document_did_open_handler(bufnr, client)
   changetracking.init(client, bufnr)
   if not client.resolved_capabilities.text_document_open_close then
@@ -548,16 +548,16 @@ end
 ---
 --- The following parameters describe fields in the {config} table.
 ---
---@param root_dir: (string) Directory where the LSP server will base
+---@param root_dir: (string) Directory where the LSP server will base
 --- its rootUri on initialization.
 ---
---@param cmd: (required, string or list treated like |jobstart()|) Base command
+---@param cmd: (required, string or list treated like |jobstart()|) Base command
 --- that initiates the LSP client.
 ---
---@param cmd_cwd: (string, default=|getcwd()|) Directory to launch
+---@param cmd_cwd: (string, default=|getcwd()|) Directory to launch
 --- the `cmd` process. Not related to `root_dir`.
 ---
---@param cmd_env: (table) Environment flags to pass to the LSP on
+---@param cmd_env: (table) Environment flags to pass to the LSP on
 --- spawn.  Can be specified using keys like a map or as a list with `k=v`
 --- pairs or both. Non-string values are coerced to string.
 --- Example:
@@ -565,7 +565,7 @@ end
 --- { "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; }
 --- </pre>
 ---
---@param capabilities Map overriding the default capabilities defined by
+---@param capabilities Map overriding the default capabilities defined by
 --- |vim.lsp.protocol.make_client_capabilities()|, passed to the language
 --- server on initialization. Hint: use make_client_capabilities() and modify
 --- its result.
@@ -573,41 +573,41 @@ end
 ---   `{[vim.type_idx]=vim.types.dictionary}`, else it will be encoded as an
 ---   array.
 ---
---@param handlers Map of language server method names to |lsp-handler|
+---@param handlers Map of language server method names to |lsp-handler|
 ---
---@param settings Map with language server specific settings. These are
+---@param settings Map with language server specific settings. These are
 --- returned to the language server if requested via `workspace/configuration`.
 --- Keys are case-sensitive.
 ---
---@param init_options Values to pass in the initialization request
+---@param init_options Values to pass in the initialization request
 --- as `initializationOptions`. See `initialize` in the LSP spec.
 ---
---@param name (string, default=client-id) Name in log messages.
+---@param name (string, default=client-id) Name in log messages.
 --
---@param workspace_folders (table) List of workspace folders passed to the
+---@param workspace_folders (table) List of workspace folders passed to the
 --- language server. Defaults to root_dir if not set. See `workspaceFolders` in
 --- the LSP spec
 ---
---@param get_language_id function(bufnr, filetype) -> language ID as string.
+---@param get_language_id function(bufnr, filetype) -> language ID as string.
 --- Defaults to the filetype.
 ---
---@param offset_encoding (default="utf-16") One of "utf-8", "utf-16",
+---@param offset_encoding (default="utf-16") One of "utf-8", "utf-16",
 --- or "utf-32" which is the encoding that the LSP server expects. Client does
 --- not verify this is correct.
 ---
---@param on_error Callback with parameters (code, ...), invoked
+---@param on_error Callback with parameters (code, ...), invoked
 --- when the client operation throws an error. `code` is a number describing
 --- the error. Other arguments may be passed depending on the error kind.  See
 --- |vim.lsp.client_errors| for possible errors.
 --- Use `vim.lsp.client_errors[code]` to get human-friendly name.
 ---
---@param before_init Callback with parameters (initialize_params, config)
+---@param before_init Callback with parameters (initialize_params, config)
 --- invoked before the LSP "initialize" phase, where `params` contains the
 --- parameters being sent to the server and `config` is the config that was
 --- passed to |vim.lsp.start_client()|. You can use this to modify parameters before
 --- they are sent.
 ---
---@param on_init Callback (client, initialize_result) invoked after LSP
+---@param on_init Callback (client, initialize_result) invoked after LSP
 --- "initialize", where `result` is a table of `capabilities` and anything else
 --- the server may send. For example, clangd sends
 --- `initialize_result.offsetEncoding` if `capabilities.offsetEncoding` was
@@ -617,24 +617,24 @@ end
 --- `workspace/didChangeConfiguration` notification should be sent
 ---  to the server during on_init.
 ---
---@param on_exit Callback (code, signal, client_id) invoked on client
+---@param on_exit Callback (code, signal, client_id) invoked on client
 --- exit.
 --- - code: exit code of the process
 --- - signal: number describing the signal used to terminate (if any)
 --- - client_id: client handle
 ---
---@param on_attach Callback (client, bufnr) invoked when client
+---@param on_attach Callback (client, bufnr) invoked when client
 --- attaches to a buffer.
 ---
---@param trace:  "off" | "messages" | "verbose" | nil passed directly to the language
+---@param trace:  "off" | "messages" | "verbose" | nil passed directly to the language
 --- server in the initialize request. Invalid/empty values will default to "off"
---@param flags: A table with flags for the client. The current (experimental) flags are:
+---@param flags: A table with flags for the client. The current (experimental) flags are:
 --- - allow_incremental_sync (bool, default true): Allow using incremental sync for buffer edits
 --- - debounce_text_changes (number, default nil): Debounce didChange
 ---       notifications to the server by the given number in milliseconds. No debounce
 ---       occurs if nil
 ---
---@returns Client id. |vim.lsp.get_client_by_id()| Note: client may not be
+---@returns Client id. |vim.lsp.get_client_by_id()| Note: client may not be
 --- fully initialized. Use `on_init` to do any actions once
 --- the client has been initialized.
 function lsp.start_client(config)
@@ -657,22 +657,22 @@ function lsp.start_client(config)
 
   local dispatch = {}
 
-  --@private
+  ---@private
   --- Returns the handler associated with an LSP method.
   --- Returns the default handler if the user hasn't set a custom one.
   ---
-  --@param method (string) LSP method name
-  --@returns (fn) The handler for the given method, if defined, or the default from |vim.lsp.handlers|
+  ---@param method (string) LSP method name
+  ---@returns (fn) The handler for the given method, if defined, or the default from |vim.lsp.handlers|
   local function resolve_handler(method)
     return handlers[method] or default_handlers[method]
   end
 
-  --@private
+  ---@private
   --- Handles a notification sent by an LSP server by invoking the
   --- corresponding handler.
   ---
-  --@param method (string) LSP method name
-  --@param params (table) The parameters for that method.
+  ---@param method (string) LSP method name
+  ---@param params (table) The parameters for that method.
   function dispatch.notification(method, params)
     local _ = log.debug() and log.debug('notification', method, params)
     local handler = resolve_handler(method)
@@ -682,11 +682,11 @@ function lsp.start_client(config)
     end
   end
 
-  --@private
+  ---@private
   --- Handles a request from an LSP server by invoking the corresponding handler.
   ---
-  --@param method (string) LSP method name
-  --@param params (table) The parameters for that method
+  ---@param method (string) LSP method name
+  ---@param params (table) The parameters for that method
   function dispatch.server_request(method, params)
     local _ = log.debug() and log.debug('server_request', method, params)
     local handler = resolve_handler(method)
@@ -698,12 +698,12 @@ function lsp.start_client(config)
     return nil, lsp.rpc_response_error(protocol.ErrorCodes.MethodNotFound)
   end
 
-  --@private
+  ---@private
   --- Invoked when the client operation throws an error.
   ---
-  --@param code (number) Error code
-  --@param err (...) Other arguments may be passed depending on the error kind
-  --@see |vim.lsp.client_errors| for possible errors. Use
+  ---@param code (number) Error code
+  ---@param err (...) Other arguments may be passed depending on the error kind
+  ---@see |vim.lsp.client_errors| for possible errors. Use
   ---`vim.lsp.client_errors[code]` to get a human-friendly name.
   function dispatch.on_error(code, err)
     local _ = log.error() and log.error(log_prefix, "on_error", { code = lsp.client_errors[code], err = err })
@@ -717,11 +717,11 @@ function lsp.start_client(config)
     end
   end
 
-  --@private
+  ---@private
   --- Invoked on client exit.
   ---
-  --@param code (number) exit code of the process
-  --@param signal (number) the signal used to terminate (if any)
+  ---@param code (number) exit code of the process
+  ---@param signal (number) the signal used to terminate (if any)
   function dispatch.on_exit(code, signal)
     active_clients[client_id] = nil
     uninitialized_clients[client_id] = nil
@@ -766,7 +766,7 @@ function lsp.start_client(config)
   -- Store the uninitialized_clients for cleanup in case we exit before initialize finishes.
   uninitialized_clients[client_id] = client;
 
-  --@private
+  ---@private
   local function initialize()
     local valid_traces = {
       off = 'off'; messages = 'messages'; verbose = 'verbose';
@@ -869,23 +869,23 @@ function lsp.start_client(config)
     end)
   end
 
-  --@private
+  ---@private
   --- Sends a request to the server.
   ---
   --- This is a thin wrapper around {client.rpc.request} with some additional
   --- checks for capabilities and handler availability.
   ---
-  --@param method (string) LSP method name.
-  --@param params (table) LSP request params.
-  --@param handler (function, optional) Response |lsp-handler| for this method.
-  --@param bufnr (number) Buffer handle (0 for current).
-  --@returns ({status}, [request_id]): {status} is a bool indicating
+  ---@param method (string) LSP method name.
+  ---@param params (table) LSP request params.
+  ---@param handler (function, optional) Response |lsp-handler| for this method.
+  ---@param bufnr (number) Buffer handle (0 for current).
+  ---@returns ({status}, [request_id]): {status} is a bool indicating
   ---whether the request was successful. If it is `false`, then it will
   ---always be `false` (the client has shutdown). If it was
   ---successful, then it will return {request_id} as the
   ---second result. You can use this with `client.cancel_request(request_id)`
   ---to cancel the-request.
-  --@see |vim.lsp.buf_request()|
+  ---@see |vim.lsp.buf_request()|
   function client.request(method, params, handler, bufnr)
     if not handler then
       handler = resolve_handler(method)
@@ -900,21 +900,21 @@ function lsp.start_client(config)
     end)
   end
 
-  --@private
+  ---@private
   --- Sends a request to the server and synchronously waits for the response.
   ---
   --- This is a wrapper around {client.request}
   ---
-  --@param method (string) LSP method name.
-  --@param params (table) LSP request params.
-  --@param timeout_ms (number, optional, default=1000) Maximum time in
+  ---@param method (string) LSP method name.
+  ---@param params (table) LSP request params.
+  ---@param timeout_ms (number, optional, default=1000) Maximum time in
   ---milliseconds to wait for a result.
-  --@param bufnr (number) Buffer handle (0 for current).
-  --@returns { err=err, result=result }, a dictionary, where `err` and `result` come from the |lsp-handler|.
+  ---@param bufnr (number) Buffer handle (0 for current).
+  ---@returns { err=err, result=result }, a dictionary, where `err` and `result` come from the |lsp-handler|.
   ---On timeout, cancel or error, returns `(nil, err)` where `err` is a
   ---string describing the failure reason. If the request was unsuccessful
   ---returns `nil`.
-  --@see |vim.lsp.buf_request_sync()|
+  ---@see |vim.lsp.buf_request_sync()|
   function client.request_sync(method, params, timeout_ms, bufnr)
     local request_result = nil
     local function _sync_handler(err, _, result)
@@ -936,25 +936,25 @@ function lsp.start_client(config)
     return request_result
   end
 
-  --@private
+  ---@private
   --- Sends a notification to an LSP server.
   ---
-  --@param method (string) LSP method name.
-  --@param params (optional, table) LSP request params.
-  --@param bufnr (number) Buffer handle, or 0 for current.
-  --@returns {status} (bool) true if the notification was successful.
+  ---@param method (string) LSP method name.
+  ---@param params (optional, table) LSP request params.
+  ---@param bufnr (number) Buffer handle, or 0 for current.
+  ---@returns {status} (bool) true if the notification was successful.
   ---If it is false, then it will always be false
   ---(the client has shutdown).
   function client.notify(...)
     return rpc.notify(...)
   end
 
-  --@private
+  ---@private
   --- Cancels a request with a given request id.
   ---
-  --@param id (number) id of request to cancel
-  --@returns true if any client returns true; false otherwise
-  --@see |vim.lsp.client.notify()|
+  ---@param id (number) id of request to cancel
+  ---@returns true if any client returns true; false otherwise
+  ---@see |vim.lsp.client.notify()|
   function client.cancel_request(id)
     validate{id = {id, 'n'}}
     return rpc.notify("$/cancelRequest", { id = id })
@@ -963,14 +963,14 @@ function lsp.start_client(config)
   -- Track this so that we can escalate automatically if we've alredy tried a
   -- graceful shutdown
   local graceful_shutdown_failed = false
-  --@private
+  ---@private
   --- Stops a client, optionally with force.
   ---
   ---By default, it will just ask the - server to shutdown without force. If
   --- you request to stop a client which has previously been requested to
   --- shutdown, it will automatically escalate and force shutdown.
   ---
-  --@param force (bool, optional)
+  ---@param force (bool, optional)
   function client.stop(force)
 
     lsp.diagnostic.reset(client_id, all_buffer_active_clients)
@@ -1000,18 +1000,18 @@ function lsp.start_client(config)
     end)
   end
 
-  --@private
+  ---@private
   --- Checks whether a client is stopped.
   ---
-  --@returns (bool) true if client is stopped or in the process of being
+  ---@returns (bool) true if client is stopped or in the process of being
   ---stopped; false otherwise
   function client.is_stopped()
     return rpc.handle:is_closing()
   end
 
-  --@private
+  ---@private
   --- Runs the on_attach function from the client's config if it was defined.
-  --@param bufnr (number) Buffer number
+  ---@param bufnr (number) Buffer number
   function client._on_attach(bufnr)
     text_document_did_open_handler(bufnr, client)
     if config.on_attach then
@@ -1025,8 +1025,8 @@ function lsp.start_client(config)
   return client_id
 end
 
---@private
---@fn text_document_did_change_handler(_, bufnr, changedtick, firstline, lastline, new_lastline, old_byte_size, old_utf32_size, old_utf16_size)
+---@private
+---@fn text_document_did_change_handler(_, bufnr, changedtick, firstline, lastline, new_lastline, old_byte_size, old_utf32_size, old_utf16_size)
 --- Notify all attached clients that a buffer has changed.
 local text_document_did_change_handler
 do
@@ -1076,8 +1076,8 @@ end
 ---
 --- Without calling this, the server won't be notified of changes to a buffer.
 ---
---- @param bufnr (number) Buffer handle, or 0 for current
---- @param client_id (number) Client id
+---@param bufnr (number) Buffer handle, or 0 for current
+---@param client_id (number) Client id
 function lsp.buf_attach_client(bufnr, client_id)
   validate {
     bufnr     = {bufnr, 'n', true};
@@ -1158,17 +1158,17 @@ end
 --- Gets a client by id, or nil if the id is invalid.
 --- The returned client may not yet be fully initialized.
 --
---@param client_id client id number
+---@param client_id client id number
 ---
---@returns |vim.lsp.client| object, or nil
+---@returns |vim.lsp.client| object, or nil
 function lsp.get_client_by_id(client_id)
   return active_clients[client_id] or uninitialized_clients[client_id]
 end
 
 --- Returns list of buffers attached to client_id.
 --
---@param client_id client id
---@returns list of buffer ids
+---@param client_id client id
+---@returns list of buffer ids
 function lsp.get_buffers_by_client_id(client_id)
   local active_client_buffers = all_client_active_buffers[client_id]
   if active_client_buffers then
@@ -1190,8 +1190,8 @@ end
 --- By default asks the server to shutdown, unless stop was requested
 --- already for this client, then force-shutdown is attempted.
 ---
---@param client_id client id or |vim.lsp.client| object, or list thereof
---@param force boolean (optional) shutdown forcefully
+---@param client_id client id or |vim.lsp.client| object, or list thereof
+---@param force boolean (optional) shutdown forcefully
 function lsp.stop_client(client_id, force)
   local ids = type(client_id) == 'table' and client_id or {client_id}
   for _, id in ipairs(ids) do
@@ -1207,7 +1207,7 @@ end
 
 --- Gets all active clients.
 ---
---@returns Table of |vim.lsp.client| objects
+---@returns Table of |vim.lsp.client| objects
 function lsp.get_active_clients()
   return vim.tbl_values(active_clients)
 end
@@ -1238,13 +1238,13 @@ nvim_command("autocmd VimLeavePre * lua vim.lsp._vim_exit_handler()")
 --- Sends an async request for all active clients attached to the
 --- buffer.
 ---
---@param bufnr (number) Buffer handle, or 0 for current.
---@param method (string) LSP method name
---@param params (optional, table) Parameters to send to the server
---@param handler (optional, function) See |lsp-handler|
+---@param bufnr (number) Buffer handle, or 0 for current.
+---@param method (string) LSP method name
+---@param params (optional, table) Parameters to send to the server
+---@param handler (optional, function) See |lsp-handler|
 --  If nil, follows resolution strategy defined in |lsp-handler-configuration|
 --
---@returns 2-tuple:
+---@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.
@@ -1296,14 +1296,14 @@ end
 ---Parameters are the same as |vim.lsp.buf_request()| but the return result and callback are
 ---different.
 ---
---@param bufnr (number) Buffer handle, or 0 for current.
---@param method (string) LSP method name
---@param params (optional, table) Parameters to send to the server
---@param callback (function) The callback to call when all requests are finished.
+---@param bufnr (number) Buffer handle, or 0 for current.
+---@param method (string) LSP method name
+---@param params (optional, table) Parameters to send to the server
+---@param callback (function) The callback to call when all requests are finished.
 --  Unlike `buf_request`, this will collect all the responses from each server instead of handling them.
 --  A map of client_id:request_result will be provided to the callback
 --
---@returns (function) A function that will cancel all requests which is the same as the one returned from `buf_request`.
+---@returns (function) A function that will cancel all requests which is the same as the one returned from `buf_request`.
 function lsp.buf_request_all(bufnr, method, params, callback)
   local request_results = {}
   local result_count = 0
@@ -1337,13 +1337,13 @@ end
 --- Parameters are the same as |vim.lsp.buf_request()| but the return result is
 --- different. Wait maximum of {timeout_ms} (default 1000) ms.
 ---
---@param bufnr (number) Buffer handle, or 0 for current.
---@param method (string) LSP method name
---@param params (optional, table) Parameters to send to the server
---@param timeout_ms (optional, number, default=1000) Maximum time in
+---@param bufnr (number) Buffer handle, or 0 for current.
+---@param method (string) LSP method name
+---@param params (optional, table) Parameters to send to the server
+---@param timeout_ms (optional, number, default=1000) Maximum time in
 ---      milliseconds to wait for a result.
 ---
---@returns Map of client_id:request_result. On timeout, cancel or error,
+---@returns Map of client_id:request_result. On timeout, cancel or error,
 ---        returns `(nil, err)` where `err` is a string describing the failure
 ---        reason.
 function lsp.buf_request_sync(bufnr, method, params, timeout_ms)
@@ -1366,11 +1366,11 @@ function lsp.buf_request_sync(bufnr, method, params, timeout_ms)
 end
 
 --- Send a notification to a server
---@param bufnr [number] (optional): The number of the buffer
---@param method [string]: Name of the request method
---@param params [string]: Arguments to send to the server
+---@param bufnr [number] (optional): The number of the buffer
+---@param method [string]: Name of the request method
+---@param params [string]: Arguments to send to the server
 ---
---@returns true if any client returns true; false otherwise
+---@returns true if any client returns true; false otherwise
 function lsp.buf_notify(bufnr, method, params)
   validate {
     bufnr    = { bufnr, 'n', true };
@@ -1385,14 +1385,14 @@ end
 
 --- Implements 'omnifunc' compatible LSP completion.
 ---
---@see |complete-functions|
---@see |complete-items|
---@see |CompleteDone|
+---@see |complete-functions|
+---@see |complete-items|
+---@see |CompleteDone|
 ---
---@param findstart 0 or 1, decides behavior
---@param base If findstart=0, text to match against
+---@param findstart 0 or 1, decides behavior
+---@param base If findstart=0, text to match against
 ---
---@returns (number) Decided by `findstart`:
+---@returns (number) 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)
@@ -1438,8 +1438,8 @@ end
 
 ---Checks whether a client is stopped.
 ---
---@param client_id (Number)
---@returns true if client is stopped, false otherwise.
+---@param client_id (Number)
+---@returns true if client is stopped, false otherwise.
 function lsp.client_is_stopped(client_id)
   return active_clients[client_id] == nil
 end
@@ -1447,7 +1447,7 @@ end
 --- Gets a map of client_id:client pairs for the given buffer, where each value
 --- is a |vim.lsp.client| object.
 ---
---@param bufnr (optional, number): Buffer handle, or 0 for current
+---@param bufnr (optional, number): Buffer handle, or 0 for current
 function lsp.buf_get_clients(bufnr)
   bufnr = resolve_bufnr(bufnr)
  local result = {}
@@ -1472,9 +1472,9 @@ lsp.log_levels = log.levels
 ---
 --- Use `lsp.log_levels` for reverse lookup.
 ---
---@see |vim.lsp.log_levels|
+---@see |vim.lsp.log_levels|
 ---
---@param level [number|string] the case insensitive level name or number
+---@param level [number|string] the case insensitive level name or number
 function lsp.set_log_level(level)
   if type(level) == 'string' or type(level) == 'number' then
     log.set_level(level)
@@ -1484,7 +1484,7 @@ function lsp.set_log_level(level)
 end
 
 --- Gets the path of the logfile used by the LSP client.
---@returns (String) Path to logfile.
+---@returns (String) Path to logfile.
 function lsp.get_log_path()
   return log.get_filename()
 end
@@ -1495,8 +1495,8 @@ function lsp.for_each_buffer_client(bufnr, fn)
 end
 
 --- Function to manage overriding defaults for LSP handlers.
---@param handler (function) See |lsp-handler|
---@param override_config (table) Table containing the keys to override behavior of the {handler}
+---@param handler (function) See |lsp-handler|
+---@param override_config (table) Table containing the keys to override behavior of the {handler}
 function lsp.with(handler, override_config)
   return function(err, method, params, client_id, bufnr, config)
     return handler(err, method, params, client_id, bufnr, vim.tbl_deep_extend("force", config or {}, override_config))
diff --git a/runtime/lua/vim/lsp/buf.lua b/runtime/lua/vim/lsp/buf.lua
index 29f8d6c3bc..250af0a0a7 100644
--- a/runtime/lua/vim/lsp/buf.lua
+++ b/runtime/lua/vim/lsp/buf.lua
@@ -5,7 +5,7 @@ local util = require 'vim.lsp.util'
 
 local M = {}
 
---@private
+---@private
 --- Returns nil if {status} is false or nil, otherwise returns the rest of the
 --- arguments.
 local function ok_or_nil(status, ...)
@@ -13,31 +13,31 @@ local function ok_or_nil(status, ...)
   return ...
 end
 
---@private
+---@private
 --- Swallows errors.
 ---
---@param fn Function to run
---@param ... Function arguments
---@returns Result of `fn(...)` if there are no errors, otherwise nil.
+---@param fn Function to run
+---@param ... Function arguments
+---@returns Result of `fn(...)` if there are no errors, otherwise nil.
 --- Returns nil if errors occur during {fn}, otherwise returns
 local function npcall(fn, ...)
   return ok_or_nil(pcall(fn, ...))
 end
 
---@private
+---@private
 --- Sends an async request to all active clients attached to the current
 --- buffer.
 ---
---@param method (string) LSP method name
---@param params (optional, table) Parameters to send to the server
---@param handler (optional, functionnil) See |lsp-handler|. Follows |lsp-handler-resolution|
+---@param method (string) LSP method name
+---@param params (optional, table) Parameters to send to the server
+---@param handler (optional, functionnil) See |lsp-handler|. Follows |lsp-handler-resolution|
 --
---@returns 2-tuple:
+---@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.
 ---
---@see |vim.lsp.buf_request()|
+---@see |vim.lsp.buf_request()|
 local function request(method, params, handler)
   validate {
     method = {method, 's'};
@@ -49,7 +49,7 @@ end
 --- Checks whether the language servers attached to the current buffer are
 --- ready.
 ---
---@returns `true` if server responds.
+---@returns `true` if server responds.
 function M.server_ready()
   return not not vim.lsp.buf_notify(0, "window/progress", {})
 end
@@ -62,7 +62,7 @@ function M.hover()
 end
 
 --- Jumps to the declaration of the symbol under the cursor.
---@note Many servers do not implement this method. Generally, see |vim.lsp.buf.definition()| instead.
+---@note Many servers do not implement this method. Generally, see |vim.lsp.buf.definition()| instead.
 ---
 function M.declaration()
   local params = util.make_position_params()
@@ -100,22 +100,22 @@ 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 (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)
 ---
---@see |vim.lsp.protocol.constants.CompletionTriggerKind|
+---@see |vim.lsp.protocol.constants.CompletionTriggerKind|
 function M.completion(context)
   local params = util.make_position_params()
   params.context = context
   return request('textDocument/completion', params)
 end
 
---@private
+---@private
 --- If there is more than one client that supports the given method,
 --- asks the user to select one.
 --
---@returns The client that the user selected or nil
+---@returns The client that the user selected or nil
 local function select_client(method)
   local clients = vim.tbl_values(vim.lsp.buf_get_clients());
   clients = vim.tbl_filter(function (client)
@@ -146,11 +146,11 @@ end
 
 --- Formats the current buffer.
 ---
---@param options (optional, table) Can be used to specify FormattingOptions.
+---@param options (optional, table) Can be used to specify FormattingOptions.
 --- Some unspecified options will be automatically derived from the current
 --- Neovim options.
 --
---@see https://microsoft.github.io/language-server-protocol/specification#textDocument_formatting
+---@see https://microsoft.github.io/language-server-protocol/specification#textDocument_formatting
 function M.formatting(options)
   local client = select_client("textDocument/formatting")
   if client == nil then return end
@@ -168,9 +168,9 @@ end
 --- vim.api.nvim_command[[autocmd BufWritePre <buffer> lua vim.lsp.buf.formatting_sync()]]
 --- </pre>
 ---
---@param options Table with valid `FormattingOptions` entries
---@param timeout_ms (number) Request timeout
---@see |vim.lsp.buf.formatting_seq_sync|
+---@param options Table with valid `FormattingOptions` entries
+---@param timeout_ms (number) Request timeout
+---@see |vim.lsp.buf.formatting_seq_sync|
 function M.formatting_sync(options, timeout_ms)
   local client = select_client("textDocument/formatting")
   if client == nil then return end
@@ -195,9 +195,9 @@ end
 --- vim.api.nvim_command[[autocmd BufWritePre <buffer> lua vim.lsp.buf.formatting_seq_sync()]]
 --- </pre>
 ---
---@param options (optional, table) `FormattingOptions` entries
---@param timeout_ms (optional, number) Request timeout
---@param order (optional, table) List of client names. Formatting is requested from clients
+---@param options (optional, table) `FormattingOptions` entries
+---@param timeout_ms (optional, number) Request timeout
+---@param order (optional, table) List of client names. Formatting is requested from clients
 ---in the following order: first all clients that are not in the `order` list, then
 ---the remaining clients in the order as they occur in the `order` list.
 function M.formatting_seq_sync(options, timeout_ms, order)
@@ -230,10 +230,10 @@ end
 
 --- Formats a given range.
 ---
---@param options Table with valid `FormattingOptions` entries.
---@param start_pos ({number, number}, optional) mark-indexed position.
+---@param options Table with valid `FormattingOptions` entries.
+---@param start_pos ({number, number}, optional) mark-indexed position.
 ---Defaults to the start of the last visual selection.
---@param end_pos ({number, number}, optional) mark-indexed position.
+---@param end_pos ({number, number}, optional) mark-indexed position.
 ---Defaults to the end of the last visual selection.
 function M.range_formatting(options, start_pos, end_pos)
   local client = select_client("textDocument/rangeFormatting")
@@ -246,7 +246,7 @@ end
 
 --- Renames all references to the symbol under the cursor.
 ---
---@param new_name (string) If not provided, the user will be prompted for a new
+---@param new_name (string) If not provided, the user will be prompted for a new
 ---name using |input()|.
 function M.rename(new_name)
   -- TODO(ashkan) use prepareRename
@@ -260,8 +260,8 @@ end
 
 --- Lists all the references to the symbol under the cursor in the quickfix window.
 ---
---@param context (table) Context for the request
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references
+---@param context (table) Context for the request
+---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references
 function M.references(context)
   validate { context = { context, 't', true } }
   local params = util.make_position_params()
@@ -279,7 +279,7 @@ function M.document_symbol()
   request('textDocument/documentSymbol', params)
 end
 
---@private
+---@private
 local function pick_call_hierarchy_item(call_hierarchy_items)
   if not call_hierarchy_items then return end
   if #call_hierarchy_items == 1 then
@@ -297,7 +297,7 @@ local function pick_call_hierarchy_item(call_hierarchy_items)
   return choice
 end
 
---@private
+---@private
 local function call_hierarchy(method)
   local params = util.make_position_params()
   request('textDocument/prepareCallHierarchy', params, function(err, _, result)
@@ -389,7 +389,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, optional)
 function M.workspace_symbol(query)
   query = query or npcall(vfn.input, "Query: ")
   local params = {query = query}
@@ -424,7 +424,7 @@ end
 
 --- Requests code actions from all clients and calls the handler exactly once
 --- with all aggregated results
---@private
+---@private
 local function code_action_request(params)
   local bufnr = vim.api.nvim_get_current_buf()
   local method = 'textDocument/codeAction'
@@ -439,9 +439,9 @@ end
 
 --- Selects a code action from the input list that is available at the current
 --- cursor position.
---
---@param context: (table, optional) Valid `CodeActionContext` object
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction
+---
+---@param context: (table, optional) Valid `CodeActionContext` object
+---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction
 function M.code_action(context)
   validate { context = { context, 't', true } }
   context = context or { diagnostics = vim.lsp.diagnostic.get_line_diagnostics() }
@@ -452,10 +452,10 @@ end
 
 --- Performs |vim.lsp.buf.code_action()| for a given range.
 ---
---@param context: (table, optional) Valid `CodeActionContext` object
---@param start_pos ({number, number}, optional) mark-indexed position.
+---@param context: (table, optional) Valid `CodeActionContext` object
+---@param start_pos ({number, number}, optional) mark-indexed position.
 ---Defaults to the start of the last visual selection.
---@param end_pos ({number, number}, optional) mark-indexed position.
+---@param end_pos ({number, number}, optional) mark-indexed position.
 ---Defaults to the end of the last visual selection.
 function M.range_code_action(context, start_pos, end_pos)
   validate { context = { context, 't', true } }
@@ -467,8 +467,8 @@ end
 
 --- Executes an LSP server command.
 ---
---@param command A valid `ExecuteCommandParams` object
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand
+---@param command A valid `ExecuteCommandParams` object
+---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand
 function M.execute_command(command)
   validate {
     command = { command.command, 's' },
diff --git a/runtime/lua/vim/lsp/codelens.lua b/runtime/lua/vim/lsp/codelens.lua
index fe581e42ad..ca5a44077e 100644
--- a/runtime/lua/vim/lsp/codelens.lua
+++ b/runtime/lua/vim/lsp/codelens.lua
@@ -22,11 +22,11 @@ local namespaces = setmetatable({}, {
   end;
 })
 
---@private
+---@private
 M.__namespaces = namespaces
 
 
---@private
+---@private
 local function execute_lens(lens, bufnr, client_id)
   local line = lens.range.start.line
   api.nvim_buf_clear_namespace(bufnr, namespaces[client_id], line, line + 1)
@@ -151,7 +151,7 @@ function M.save(lenses, bufnr, client_id)
 end
 
 
---@private
+---@private
 local function resolve_lenses(lenses, bufnr, client_id, callback)
   lenses = lenses or {}
   local num_lens = vim.tbl_count(lenses)
@@ -160,7 +160,7 @@ local function resolve_lenses(lenses, bufnr, client_id, callback)
     return
   end
 
-  --@private
+  ---@private
   local function countdown()
     num_lens = num_lens - 1
     if num_lens == 0 then
diff --git a/runtime/lua/vim/lsp/diagnostic.lua b/runtime/lua/vim/lsp/diagnostic.lua
index a244e3d6a4..45aeb17465 100644
--- a/runtime/lua/vim/lsp/diagnostic.lua
+++ b/runtime/lua/vim/lsp/diagnostic.lua
@@ -8,7 +8,7 @@ local util = require('vim.lsp.util')
 
 local if_nil = vim.F.if_nil
 
---@class DiagnosticSeverity
+---@class DiagnosticSeverity
 local DiagnosticSeverity = protocol.DiagnosticSeverity
 
 local to_severity = function(severity)
@@ -46,14 +46,14 @@ end
 
 ---@brief lsp-diagnostic
 ---
---@class Diagnostic
---@field range Range
---@field message string
---@field severity DiagnosticSeverity|nil
---@field code number | string
---@field source string
---@field tags DiagnosticTag[]
---@field relatedInformation DiagnosticRelatedInformation[]
+---@class Diagnostic
+---@field range Range
+---@field message string
+---@field severity DiagnosticSeverity|nil
+---@field code number | string
+---@field source string
+---@field tags DiagnosticTag[]
+---@field relatedInformation DiagnosticRelatedInformation[]
 
 local M = {}
 
@@ -167,12 +167,12 @@ end
 local _diagnostic_namespaces = _make_namespace_table("vim_lsp_diagnostics", true)
 local _sign_namespaces = _make_namespace_table("vim_lsp_signs", false)
 
---@private
+---@private
 function M._get_diagnostic_namespace(client_id)
   return _diagnostic_namespaces[client_id]
 end
 
---@private
+---@private
 function M._get_sign_namespace(client_id)
   return _sign_namespaces[client_id]
 end
@@ -255,7 +255,7 @@ local _diagnostic_counts = function(diagnostics)
   return counts
 end
 
---@private
+---@private
 --- Set the different diagnostic cache after `textDocument/publishDiagnostics`
 ---@param diagnostics Diagnostic[]
 ---@param bufnr number
@@ -291,7 +291,7 @@ local function set_diagnostic_cache(diagnostics, bufnr, client_id)
 end
 
 
---@private
+---@private
 --- Clear the cached diagnostics
 ---@param bufnr number
 ---@param client_id number
@@ -512,7 +512,7 @@ local _next_diagnostic = function(position, search_forward, bufnr, opts, client_
   end
 end
 
---@private
+---@private
 --- Helper function to return a position from a diagnostic
 ---
 ---@return table {row, col}
@@ -527,7 +527,7 @@ local function _diagnostic_pos(opts, diagnostic)
   return to_position(diagnostic.range.start, bufnr)
 end
 
---@private
+---@private
 -- Move to the diagnostic position
 local function _diagnostic_move_pos(name, opts, pos)
   opts = opts or {}
@@ -858,7 +858,7 @@ end
 --- Callback scheduled for after leaving insert mode
 ---
 --- Used to handle
---@private
+---@private
 function M._execute_scheduled_display(bufnr, client_id)
   local args = _bufs_waiting_to_update[bufnr][client_id]
   if not args then
@@ -924,20 +924,20 @@ end
 
 -- Diagnostic Private Highlight Utilies {{{
 --- Get the severity highlight name
---@private
+---@private
 function M._get_severity_highlight_name(severity)
   return virtual_text_highlight_map[severity]
 end
 
 --- Get floating severity highlight name
---@private
+---@private
 function M._get_floating_severity_highlight_name(severity)
   return floating_highlight_map[severity]
 end
 
 --- This should be called to update the highlights for the LSP client.
 function M._define_default_signs_and_highlights()
-  --@private
+  ---@private
   local function define_default_sign(name, properties)
     if vim.tbl_isempty(vim.fn.sign_getdefined(name)) then
       vim.fn.sign_define(name, properties)
@@ -1054,8 +1054,8 @@ function M.on_publish_diagnostics(_, _, params, client_id, _, config)
 end
 
 -- restores the extmarks set by M.display
---- @param last number last line that was changed
--- @private
+---@param last number last line that was changed
+---@private
 local function restore_extmarks(bufnr, last)
   for client_id, extmarks in pairs(diagnostic_cache_extmarks[bufnr]) do
     local ns = M._get_diagnostic_namespace(client_id)
@@ -1084,7 +1084,7 @@ local function restore_extmarks(bufnr, last)
 end
 
 -- caches the extmarks set by M.display
--- @private
+---@private
 local function save_extmarks(bufnr, client_id)
   bufnr = bufnr == 0 and api.nvim_get_current_buf() or bufnr
   if not diagnostic_attached_buffers[bufnr] then
@@ -1101,7 +1101,7 @@ local function save_extmarks(bufnr, client_id)
   diagnostic_cache_extmarks[bufnr][client_id] = api.nvim_buf_get_extmarks(bufnr, ns, 0, -1, {details = true})
 end
 
---@private
+---@private
 --- Display diagnostics for the buffer, given a configuration.
 function M.display(diagnostics, bufnr, client_id, config)
   if diagnostic_disabled[bufnr][client_id] then
@@ -1187,10 +1187,10 @@ end
 --- for redrawing diagnostics after making changes in diagnostics
 --- configuration. |lsp-handler-configuration|
 ---
---- @param bufnr (optional, number): Buffer handle, defaults to current
---- @param client_id (optional, number): Redraw diagnostics for the given
----        client. The default is to redraw diagnostics for all attached
----        clients.
+---@param bufnr (optional, number): Buffer handle, defaults to current
+---@param client_id (optional, number): Redraw diagnostics for the given
+---       client. The default is to redraw diagnostics for all attached
+---       clients.
 function M.redraw(bufnr, client_id)
   bufnr = get_bufnr(bufnr)
   if not client_id then
@@ -1410,10 +1410,10 @@ function M.set_loclist(opts)
 end
 
 --- Disable diagnostics for the given buffer and client
---- @param bufnr (optional, number): Buffer handle, defaults to current
---- @param client_id (optional, number): Disable diagnostics for the given
----        client. The default is to disable diagnostics for all attached
----        clients.
+---@param bufnr (optional, number): Buffer handle, defaults to current
+---@param client_id (optional, number): Disable diagnostics for the given
+---       client. The default is to disable diagnostics for all attached
+---       clients.
 -- Note that when diagnostics are disabled for a buffer, the server will still
 -- send diagnostic information and the client will still process it. The
 -- diagnostics are simply not displayed to the user.
@@ -1429,10 +1429,10 @@ function M.disable(bufnr, client_id)
 end
 
 --- Enable diagnostics for the given buffer and client
---- @param bufnr (optional, number): Buffer handle, defaults to current
---- @param client_id (optional, number): Enable diagnostics for the given
----        client. The default is to enable diagnostics for all attached
----        clients.
+---@param bufnr (optional, number): Buffer handle, defaults to current
+---@param client_id (optional, number): Enable diagnostics for the given
+---       client. The default is to enable diagnostics for all attached
+---       clients.
 function M.enable(bufnr, client_id)
   if not client_id then
     return vim.lsp.for_each_buffer_client(bufnr, function(client)
diff --git a/runtime/lua/vim/lsp/handlers.lua b/runtime/lua/vim/lsp/handlers.lua
index b7f1ea0ab6..befb9fcec3 100644
--- a/runtime/lua/vim/lsp/handlers.lua
+++ b/runtime/lua/vim/lsp/handlers.lua
@@ -9,9 +9,9 @@ local M = {}
 
 -- FIXME: DOC: Expose in vimdocs
 
---@private
+---@private
 --- Writes to error buffer.
---@param ... (table of strings) Will be concatenated before being written
+---@param ... (table of strings) Will be concatenated before being written
 local function err_message(...)
   vim.notify(table.concat(vim.tbl_flatten{...}), vim.log.levels.ERROR)
   api.nvim_command("redraw")
@@ -22,7 +22,7 @@ M['workspace/executeCommand'] = function()
   -- Error handling is done implicitly by wrapping all handlers; see end of this file
 end
 
---@private
+---@private
 local function progress_handler(_, _, params, client_id)
   local client = vim.lsp.get_client_by_id(client_id)
   local client_name = client and client.name or string.format("id=%d", client_id)
@@ -189,7 +189,7 @@ end
 
 
 
---@private
+---@private
 --- Return a function that converts LSP responses to list items and opens the list
 ---
 --- The returned function has an optional {config} parameter that accepts a table
@@ -197,8 +197,8 @@ end
 ---
 ---   loclist: (boolean) use the location list (default is to use the quickfix list)
 ---
---- @param map_result function `((resp, bufnr) -> list)` to convert the response
---- @param entity name of the resource used in a `not found` error message
+---@param map_result function `((resp, bufnr) -> list)` to convert the response
+---@param entity name of the resource used in a `not found` error message
 local function response_to_list(map_result, entity)
   return function(_, _, result, _, bufnr, config)
     if not result or vim.tbl_isempty(result) then
@@ -289,11 +289,11 @@ end
 --see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
 M['textDocument/hover'] = M.hover
 
---@private
+---@private
 --- Jumps to a location. Used as a handler for multiple LSP methods.
---@param _ (not used)
---@param method (string) LSP method name
---@param result (table) result of LSP method; a location or a list of locations.
+---@param _ (not used)
+---@param method (string) LSP method name
+---@param result (table) result of LSP method; a location or a list of locations.
 ---(`textDocument/definition` can return `Location` or `Location[]`
 local function location_handler(_, method, result)
   if result == nil or vim.tbl_isempty(result) then
@@ -377,13 +377,13 @@ M['textDocument/documentHighlight'] = function(_, _, result, _, bufnr, _)
   util.buf_highlight_references(bufnr, result)
 end
 
---@private
+---@private
 ---
 --- 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"`,
+---@param direction `"from"` for incoming calls and `"to"` for outgoing calls
+---@returns `CallHierarchyIncomingCall[]` if {direction} is `"from"`,
+---@returns `CallHierarchyOutgoingCall[]` if {direction} is `"to"`,
 local make_call_hierarchy_handler = function(direction)
   return function(_, _, result)
     if not result then return end
diff --git a/runtime/lua/vim/lsp/log.lua b/runtime/lua/vim/lsp/log.lua
index 73fafb9715..a2d5c3a774 100644
--- a/runtime/lua/vim/lsp/log.lua
+++ b/runtime/lua/vim/lsp/log.lua
@@ -18,14 +18,14 @@ local log_date_format = "%FT%H:%M:%S%z"
 
 do
   local path_sep = vim.loop.os_uname().version:match("Windows") and "\\" or "/"
-  --@private
+  ---@private
   local function path_join(...)
     return table.concat(vim.tbl_flatten{...}, path_sep)
   end
   local logfilename = path_join(vim.fn.stdpath('cache'), 'lsp.log')
 
   --- Returns the log filename.
-  --@returns (string) log filename
+  ---@returns (string) log filename
   function log.get_filename()
     return logfilename
   end
@@ -77,7 +77,7 @@ end
 vim.tbl_add_reverse_lookup(log.levels)
 
 --- Sets the current log level.
---@param level (string or number) One of `vim.lsp.log.levels`
+---@param level (string or number) One of `vim.lsp.log.levels`
 function log.set_level(level)
   if type(level) == 'string' then
     current_log_level = assert(log.levels[level:upper()], string.format("Invalid log level: %q", level))
@@ -89,8 +89,8 @@ function log.set_level(level)
 end
 
 --- Checks whether the level is sufficient for logging.
---@param level number log level
---@returns (bool) true if would log, false if not
+---@param level number log level
+---@returns (bool) true if would log, false if not
 function log.should_log(level)
   return level >= current_log_level
 end
diff --git a/runtime/lua/vim/lsp/protocol.lua b/runtime/lua/vim/lsp/protocol.lua
index 6d02b9ba74..ded8af5773 100644
--- a/runtime/lua/vim/lsp/protocol.lua
+++ b/runtime/lua/vim/lsp/protocol.lua
@@ -5,14 +5,14 @@ local if_nil = vim.F.if_nil
 local protocol = {}
 
 --[=[
---@private
+---@private
 --- Useful for interfacing with:
 --- https://github.com/microsoft/language-server-protocol/raw/gh-pages/_specifications/specification-3-14.md
 function transform_schema_comments()
   nvim.command [[silent! '<,'>g/\/\*\*\|\*\/\|^$/d]]
   nvim.command [[silent! '<,'>s/^\(\s*\) \* \=\(.*\)/\1--\2/]]
 end
---@private
+---@private
 function transform_schema_to_table()
   transform_schema_comments()
   nvim.command [[silent! '<,'>s/: \S\+//]]
diff --git a/runtime/lua/vim/lsp/rpc.lua b/runtime/lua/vim/lsp/rpc.lua
index 4c5f02af9d..eedb708118 100644
--- a/runtime/lua/vim/lsp/rpc.lua
+++ b/runtime/lua/vim/lsp/rpc.lua
@@ -5,11 +5,11 @@ local protocol = require('vim.lsp.protocol')
 local validate, schedule, schedule_wrap = vim.validate, vim.schedule, vim.schedule_wrap
 
 -- TODO replace with a better implementation.
---@private
+---@private
 --- Encodes to JSON.
 ---
---@param data (table) Data to encode
---@returns (string) Encoded object
+---@param data (table) Data to encode
+---@returns (string) Encoded object
 local function json_encode(data)
   local status, result = pcall(vim.fn.json_encode, data)
   if status then
@@ -18,11 +18,11 @@ local function json_encode(data)
     return nil, result
   end
 end
---@private
+---@private
 --- Decodes from JSON.
 ---
---@param data (string) Data to decode
---@returns (table) Decoded JSON object
+---@param data (string) Data to decode
+---@returns (table) Decoded JSON object
 local function json_decode(data)
   local status, result = pcall(vim.fn.json_decode, data)
   if status then
@@ -32,10 +32,10 @@ local function json_decode(data)
   end
 end
 
---@private
+---@private
 --- Checks whether a given path exists and is a directory.
---@param filename (string) path to check
---@returns (bool)
+---@param filename (string) path to check
+---@returns (bool)
 local function is_dir(filename)
   local stat = vim.loop.fs_stat(filename)
   return stat and stat.type == 'directory' or false
@@ -43,7 +43,7 @@ end
 
 local NIL = vim.NIL
 
---@private
+---@private
 local recursive_convert_NIL
 recursive_convert_NIL = function(v, tbl_processed)
   if v == NIL then
@@ -63,15 +63,15 @@ recursive_convert_NIL = function(v, tbl_processed)
   return v
 end
 
---@private
+---@private
 --- Returns its argument, but converts `vim.NIL` to Lua `nil`.
---@param v (any) Argument
---@returns (any)
+---@param v (any) Argument
+---@returns (any)
 local function convert_NIL(v)
   return recursive_convert_NIL(v, {})
 end
 
---@private
+---@private
 --- Merges current process env with the given env and returns the result as
 --- a list of "k=v" strings.
 ---
@@ -81,8 +81,8 @@ end
 ---  in:    { PRODUCTION="false", PATH="/usr/bin/", PORT=123, HOST="0.0.0.0", }
 ---  out:   { "PRODUCTION=false", "PATH=/usr/bin/", "PORT=123", "HOST=0.0.0.0", }
 --- </pre>
---@param env (table) table of environment variable assignments
---@returns (table) list of `"k=v"` strings
+---@param env (table) table of environment variable assignments
+---@returns (table) list of `"k=v"` strings
 local function env_merge(env)
   if env == nil then
     return env
@@ -97,11 +97,11 @@ local function env_merge(env)
   return final_env
 end
 
---@private
+---@private
 --- 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
+---@param encoded_message (string)
+---@returns (table) table containing encoded message and `Content-Length` attribute
 local function format_message_with_content_length(encoded_message)
   return table.concat {
     'Content-Length: '; tostring(#encoded_message); '\r\n\r\n';
@@ -109,11 +109,11 @@ local function format_message_with_content_length(encoded_message)
   }
 end
 
---@private
+---@private
 --- Parses an LSP Message's header
 ---
---@param header: The header to parse.
---@returns Parsed headers
+---@param header: The header to parse.
+---@returns Parsed headers
 local function parse_headers(header)
   if type(header) ~= 'string' then
     return nil
@@ -141,7 +141,7 @@ end
 -- case insensitive pattern.
 local header_start_pattern = ("content"):gsub("%w", function(c) return "["..c..c:upper().."]" end)
 
---@private
+---@private
 --- The actual workhorse.
 local function request_parser_loop()
   local buffer = '' -- only for header part
@@ -203,8 +203,8 @@ local client_errors = vim.tbl_add_reverse_lookup {
 
 --- Constructs an error message from an LSP error object.
 ---
---@param err (table) The error object
---@returns (string) The formatted error message
+---@param err (table) The error object
+---@returns (string) The formatted error message
 local function format_rpc_error(err)
   validate {
     err = { err, 't' };
@@ -233,9 +233,9 @@ end
 
 --- Creates an RPC response object/table.
 ---
---@param code RPC error code defined in `vim.lsp.protocol.ErrorCodes`
---@param message (optional) arbitrary message to send to server
---@param data (optional) arbitrary data to send to server
+---@param code RPC error code defined in `vim.lsp.protocol.ErrorCodes`
+---@param message (optional) arbitrary message to send to server
+---@param data (optional) arbitrary data to send to server
 local function rpc_response_error(code, message, data)
   -- TODO should this error or just pick a sane error (like InternalError)?
   local code_name = assert(protocol.ErrorCodes[code], 'Invalid RPC error code')
@@ -250,38 +250,38 @@ end
 
 local default_dispatchers = {}
 
---@private
+---@private
 --- Default dispatcher for notifications sent to an LSP server.
 ---
---@param method (string) The invoked LSP method
---@param params (table): Parameters for the invoked LSP method
+---@param method (string) The invoked LSP method
+---@param params (table): Parameters for the invoked LSP method
 function default_dispatchers.notification(method, params)
   local _ = log.debug() and log.debug('notification', method, params)
 end
---@private
+---@private
 --- Default dispatcher for requests sent to an LSP server.
 ---
---@param method (string) The invoked LSP method
---@param params (table): Parameters for the invoked LSP method
---@returns `nil` and `vim.lsp.protocol.ErrorCodes.MethodNotFound`.
+---@param method (string) The invoked LSP method
+---@param params (table): Parameters for the invoked LSP method
+---@returns `nil` and `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)
 end
---@private
+---@private
 --- Default dispatcher for when a client exits.
 ---
---@param code (number): Exit code
---@param signal (number): Number describing the signal used to terminate (if
+---@param code (number): Exit code
+---@param signal (number): Number describing the signal used to terminate (if
 ---any)
 function default_dispatchers.on_exit(code, signal)
   local _ = log.info() and log.info("client_exit", { code = code, signal = signal })
 end
---@private
+---@private
 --- Default dispatcher for client errors.
 ---
---@param code (number): Error code
---@param err (any): Details about the error
+---@param code (number): Error code
+---@param err (any): Details about the error
 ---any)
 function default_dispatchers.on_error(code, err)
   local _ = log.error() and log.error('client_error:', client_errors[code], err)
@@ -290,25 +290,25 @@ end
 --- Starts an LSP server process and create an LSP RPC client object to
 --- interact with it.
 ---
---@param cmd (string) Command to start the LSP server.
---@param cmd_args (table) List of additional string arguments to pass to {cmd}.
---@param dispatchers (table, optional) Dispatchers for LSP message types. Valid
+---@param cmd (string) Command to start the LSP server.
+---@param cmd_args (table) List of additional string arguments to pass to {cmd}.
+---@param dispatchers (table, optional) Dispatchers for LSP message types. Valid
 ---dispatcher names are:
 --- - `"notification"`
 --- - `"server_request"`
 --- - `"on_error"`
 --- - `"on_exit"`
---@param extra_spawn_params (table, optional) Additional context for the LSP
+---@param extra_spawn_params (table, optional) Additional context for the LSP
 --- 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 Client RPC object.
 ---
---@returns Methods:
+---@returns Methods:
 --- - `notify()` |vim.lsp.rpc.notify()|
 --- - `request()` |vim.lsp.rpc.request()|
 ---
---@returns Members:
+---@returns Members:
 --- - {pid} (number) The LSP server's PID.
 --- - {handle} A handle for low-level interaction with the LSP server process
 ---   |vim.loop|.
@@ -358,10 +358,10 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
 
   local handle, pid
   do
-    --@private
+    ---@private
     --- Callback for |vim.loop.spawn()| Closes all streams and runs the `on_exit` dispatcher.
-    --@param code (number) Exit code
-    --@param signal (number) Signal that was used to terminate (if any)
+    ---@param code (number) Exit code
+    ---@param signal (number) Signal that was used to terminate (if any)
     local function onexit(code, signal)
       stdin:close()
       stdout:close()
@@ -385,12 +385,12 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
     end
   end
 
-  --@private
+  ---@private
   --- Encodes {payload} into a JSON-RPC message and sends it to the remote
   --- process.
   ---
-  --@param payload (table) Converted into a JSON string, see |json_encode()|
-  --@returns true if the payload could be scheduled, false if the main event-loop is in the process of closing.
+  ---@param payload (table) Converted into a JSON string, see |json_encode()|
+  ---@returns true if the payload could be scheduled, false if the main event-loop is in the process of closing.
   local function encode_and_send(payload)
     local _ = log.debug() and log.debug("rpc.send.payload", payload)
     if handle == nil or handle:is_closing() then return false end
@@ -406,9 +406,9 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
   -- `start()`
   --
   --- Sends a notification to the LSP server.
-  --@param method (string) The invoked LSP method
-  --@param params (table): Parameters for the invoked LSP method
-  --@returns (bool) `true` if notification could be sent, `false` if not
+  ---@param method (string) The invoked LSP method
+  ---@param params (table): Parameters for the invoked LSP method
+  ---@returns (bool) `true` if notification could be sent, `false` if not
   local function notify(method, params)
     return encode_and_send {
       jsonrpc = "2.0";
@@ -417,7 +417,7 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
     }
   end
 
-  --@private
+  ---@private
   --- sends an error object to the remote LSP process.
   local function send_response(request_id, err, result)
     return encode_and_send {
@@ -433,10 +433,10 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
   --
   --- Sends a request to the LSP server and runs {callback} upon response.
   ---
-  --@param method (string) The invoked LSP method
-  --@param params (table) Parameters for the invoked LSP method
-  --@param callback (function) Callback to invoke
-  --@returns (bool, number) `(true, message_id)` if request could be sent, `false` if not
+  ---@param method (string) The invoked LSP method
+  ---@param params (table) Parameters for the invoked LSP method
+  ---@param callback (function) Callback to invoke
+  ---@returns (bool, number) `(true, message_id)` if request could be sent, `false` if not
   local function request(method, params, callback)
     validate {
       callback = { callback, 'f' };
@@ -463,13 +463,13 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
     end
   end)
 
-  --@private
+  ---@private
   local function on_error(errkind, ...)
     assert(client_errors[errkind])
     -- TODO what to do if this fails?
     pcall(dispatchers.on_error, errkind, ...)
   end
-  --@private
+  ---@private
   local function pcall_handler(errkind, status, head, ...)
     if not status then
       on_error(errkind, head, ...)
@@ -477,7 +477,7 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
     end
     return status, head, ...
   end
-  --@private
+  ---@private
   local function try_call(errkind, fn, ...)
     return pcall_handler(errkind, pcall(fn, ...))
   end
@@ -486,7 +486,7 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
   -- time and log them. This would require storing the timestamp. I could call
   -- them with an error then, perhaps.
 
-  --@private
+  ---@private
   local function handle_body(body)
     local decoded, err = json_decode(body)
     if not decoded then
diff --git a/runtime/lua/vim/lsp/util.lua b/runtime/lua/vim/lsp/util.lua
index d682fdc17e..a4b3298fd8 100644
--- a/runtime/lua/vim/lsp/util.lua
+++ b/runtime/lua/vim/lsp/util.lua
@@ -40,10 +40,10 @@ local loclist_type_map = {
 }
 
 
---@private
--- Check the border given by opts or the default border for the additional
--- size it adds to a float.
---@returns size of border in height and width
+---@private
+--- Check the border given by opts or the default border for the additional
+--- size it adds to a float.
+---@returns size of border in height and width
 local function get_border_size(opts)
   local border = opts and opts.border or default_border
   local height = 0
@@ -86,7 +86,7 @@ local function get_border_size(opts)
   return { height = height, width = width }
 end
 
---@private
+---@private
 local function split_lines(value)
   return split(value, '\n', true)
 end
@@ -95,11 +95,11 @@ end
 ---
 --- CAUTION: Changes in-place!
 ---
---@param lines (table) Original list of strings
---@param A (table) Start position; a 2-tuple of {line, col} numbers
---@param B (table) End position; a 2-tuple of {line, col} numbers
---@param new_lines A list of strings to replace the original
---@returns (table) The modified {lines} object
+---@param lines (table) Original list of strings
+---@param A (table) Start position; a 2-tuple of {line, col} numbers
+---@param B (table) End position; a 2-tuple of {line, col} numbers
+---@param new_lines A list of strings to replace the original
+---@returns (table) The modified {lines} object
 function M.set_lines(lines, A, B, new_lines)
   -- 0-indexing to 1-indexing
   local i_0 = A[1] + 1
@@ -133,7 +133,7 @@ function M.set_lines(lines, A, B, new_lines)
   return lines
 end
 
---@private
+---@private
 local function sort_by_key(fn)
   return function(a,b)
     local ka, kb = fn(a), fn(b)
@@ -147,12 +147,12 @@ local function sort_by_key(fn)
     return false
   end
 end
---@private
+---@private
 local edit_sort_key = sort_by_key(function(e)
   return {e.A[1], e.A[2], e.i}
 end)
 
---@private
+---@private
 --- Position is a https://microsoft.github.io/language-server-protocol/specifications/specification-current/#position
 --- Returns a zero-indexed column, since set_lines() does the conversion to
 --- 1-indexed
@@ -238,8 +238,8 @@ function M.get_progress_messages()
 end
 
 --- Applies a list of text edits to a buffer.
---@param text_edits (table) list of `TextEdit` objects
---@param buf_nr (number) Buffer id
+---@param text_edits (table) list of `TextEdit` objects
+---@param buf_nr (number) Buffer id
 ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textEdit
 function M.apply_text_edits(text_edits, bufnr)
   if not next(text_edits) then return end
@@ -295,11 +295,11 @@ end
 -- function M.glob_to_regex(glob)
 -- end
 
---@private
+---@private
 --- Finds the first line and column of the difference between old and new lines
---@param old_lines table list of lines
---@param new_lines table list of lines
---@returns (int, int) start_line_idx and start_col_idx of range
+---@param old_lines table list of lines
+---@param new_lines table list of lines
+---@returns (int, int) start_line_idx and start_col_idx of range
 local function first_difference(old_lines, new_lines, start_line_idx)
   local line_count = math.min(#old_lines, #new_lines)
   if line_count == 0 then return 1, 1 end
@@ -325,12 +325,12 @@ local function first_difference(old_lines, new_lines, start_line_idx)
 end
 
 
---@private
+---@private
 --- Finds the last line and column of the differences between old and new lines
---@param old_lines table list of lines
---@param new_lines table list of lines
---@param start_char integer First different character idx of range
---@returns (int, int) end_line_idx and end_col_idx of range
+---@param old_lines table list of lines
+---@param new_lines table list of lines
+---@param start_char integer First different character idx of range
+---@returns (int, int) end_line_idx and end_col_idx of range
 local function last_difference(old_lines, new_lines, start_char, end_line_idx)
   local line_count = math.min(#old_lines, #new_lines)
   if line_count == 0 then return 0,0 end
@@ -369,14 +369,14 @@ local function last_difference(old_lines, new_lines, start_char, end_line_idx)
 
 end
 
---@private
+---@private
 --- Get the text of the range defined by start and end line/column
---@param lines table list of lines
---@param start_char integer First different character idx of range
---@param end_char integer Last different character idx of range
---@param start_line integer First different line idx of range
---@param end_line integer Last different line idx of range
---@returns string text extracted from defined region
+---@param lines table list of lines
+---@param start_char integer First different character idx of range
+---@param end_char integer Last different character idx of range
+---@param start_line integer First different line idx of range
+---@param end_line integer Last different line idx of range
+---@returns string text extracted from defined region
 local function extract_text(lines, start_line, start_char, end_line, end_char)
   if start_line == #lines + end_line + 1 then
     if end_line == 0 then return '' end
@@ -396,14 +396,14 @@ local function extract_text(lines, start_line, start_char, end_line, end_char)
   return result
 end
 
---@private
+---@private
 --- Compute the length of the substituted range
---@param lines table list of lines
---@param start_char integer First different character idx of range
---@param end_char integer Last different character idx of range
---@param start_line integer First different line idx of range
---@param end_line integer Last different line idx of range
---@returns (int, int) end_line_idx and end_col_idx of range
+---@param lines table list of lines
+---@param start_char integer First different character idx of range
+---@param end_char integer Last different character idx of range
+---@param start_line integer First different line idx of range
+---@param end_line integer Last different line idx of range
+---@returns (int, int) end_line_idx and end_col_idx of range
 local function compute_length(lines, start_line, start_char, end_line, end_char)
   local adj_end_line = #lines + end_line + 1
   local adj_end_char
@@ -424,12 +424,12 @@ local function compute_length(lines, start_line, start_char, end_line, end_char)
 end
 
 --- Returns the range table for the difference between old and new lines
---@param old_lines table list of lines
---@param new_lines table list of lines
---@param start_line_idx int line to begin search for first difference
---@param end_line_idx int line to begin search for last difference
---@param offset_encoding string encoding requested by language server
---@returns table start_line_idx and start_col_idx of range
+---@param old_lines table list of lines
+---@param new_lines table list of lines
+---@param start_line_idx int line to begin search for first difference
+---@param end_line_idx int line to begin search for last difference
+---@param offset_encoding string encoding requested by language server
+---@returns table start_line_idx and start_col_idx of range
 function M.compute_diff(old_lines, new_lines, start_line_idx, end_line_idx, offset_encoding)
   local start_line, start_char = first_difference(old_lines, new_lines, start_line_idx)
   local end_line, end_char = last_difference(vim.list_slice(old_lines, start_line, #old_lines),
@@ -469,9 +469,9 @@ end
 --- Can be used to extract the completion items from a
 --- `textDocument/completion` request, which may return one of
 --- `CompletionItem[]`, `CompletionList` or null.
---@param result (table) The result of a `textDocument/completion` request
---@returns (table) List of completion items
---@see https://microsoft.github.io/language-server-protocol/specification#textDocument_completion
+---@param result (table) The result of a `textDocument/completion` request
+---@returns (table) List of completion items
+---@see https://microsoft.github.io/language-server-protocol/specification#textDocument_completion
 function M.extract_completion_items(result)
   if type(result) == 'table' and result.items then
     -- result is a `CompletionList`
@@ -515,12 +515,12 @@ function M.apply_text_document_edit(text_document_edit, index)
   M.apply_text_edits(text_document_edit.edits, bufnr)
 end
 
---@private
+---@private
 --- Recursively parses snippets in a completion entry.
 ---
---@param input (string) Snippet text to parse for snippets
---@param inner (bool) Whether this function is being called recursively
---@returns 2-tuple of strings: The first is the parsed result, the second is the
+---@param input (string) Snippet text to parse for snippets
+---@param inner (bool) Whether this function is being called recursively
+---@returns 2-tuple of strings: The first is the parsed result, the second is the
 ---unparsed rest of the input
 local function parse_snippet_rec(input, inner)
   local res = ""
@@ -577,28 +577,28 @@ end
 
 --- Parses snippets in a completion entry.
 ---
---@param input (string) unparsed snippet
---@returns (string) parsed snippet
+---@param input (string) unparsed snippet
+---@returns (string) parsed snippet
 function M.parse_snippet(input)
   local res, _ = parse_snippet_rec(input, false)
 
   return res
 end
 
---@private
+---@private
 --- Sorts by CompletionItem.sortText.
 ---
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_completion
+--see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_completion
 local function sort_completion_items(items)
   table.sort(items, function(a, b)
     return (a.sortText or a.label) < (b.sortText or b.label)
   end)
 end
 
---@private
+---@private
 --- Returns text that should be inserted when selecting completion item. The
 --- precedence is as follows: textEdit.newText > insertText > label
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_completion
+--see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_completion
 local function get_completion_word(item)
   if item.textEdit ~= nil and item.textEdit.newText ~= nil and item.textEdit.newText ~= "" then
     local insert_text_format = protocol.InsertTextFormat[item.insertTextFormat]
@@ -618,7 +618,7 @@ local function get_completion_word(item)
   return item.label
 end
 
---@private
+---@private
 --- Some language servers return complementary candidates whose prefixes do not
 --- match are also returned. So we exclude completion candidates whose prefix
 --- does not match.
@@ -633,9 +633,9 @@ end
 --- the client must handle it properly even if it receives a value outside the
 --- specification.
 ---
---@param completion_item_kind (`vim.lsp.protocol.completionItemKind`)
---@returns (`vim.lsp.protocol.completionItemKind`)
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_completion
+---@param completion_item_kind (`vim.lsp.protocol.completionItemKind`)
+---@returns (`vim.lsp.protocol.completionItemKind`)
+---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_completion
 function M._get_completion_item_kind_name(completion_item_kind)
   return protocol.CompletionItemKind[completion_item_kind] or "Unknown"
 end
@@ -643,12 +643,12 @@ end
 --- Turns the result of a `textDocument/completion` request into vim-compatible
 --- |complete-items|.
 ---
---@param result The result of a `textDocument/completion` call, e.g. from
+---@param result The result of a `textDocument/completion` call, e.g. from
 ---|vim.lsp.buf.completion()|, which may be one of `CompletionItem[]`,
 --- `CompletionList` or `null`
---@param prefix (string) the prefix to filter the completion items
---@returns { matches = complete-items table, incomplete = bool }
---@see |complete-items|
+---@param prefix (string) the prefix to filter the completion items
+---@returns { matches = complete-items table, incomplete = bool }
+---@see |complete-items|
 function M.text_document_completion_list_to_complete_items(result, prefix)
   local items = M.extract_completion_items(result)
   if vim.tbl_isempty(items) then
@@ -698,8 +698,8 @@ end
 
 
 --- Rename old_fname to new_fname
---
---@param opts (table)
+---
+---@param opts (table)
 --         overwrite? bool
 --         ignoreIfExists? bool
 function M.rename(old_fname, new_fname, opts)
@@ -754,8 +754,8 @@ end
 
 --- Applies a `WorkspaceEdit`.
 ---
---@param workspace_edit (table) `WorkspaceEdit`
--- @see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_applyEdit
+---@param workspace_edit (table) `WorkspaceEdit`
+--see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_applyEdit
 function M.apply_workspace_edit(workspace_edit)
   if workspace_edit.documentChanges then
     for idx, change in ipairs(workspace_edit.documentChanges) do
@@ -794,10 +794,10 @@ end
 --- window for `textDocument/hover`, for parsing the result of
 --- `textDocument/signatureHelp`, and potentially others.
 ---
---@param input (`MarkedString` | `MarkedString[]` | `MarkupContent`)
---@param contents (table, optional, default `{}`) List of strings to extend with converted lines
---@returns {contents}, extended with lines of converted markdown.
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
+---@param input (`MarkedString` | `MarkedString[]` | `MarkupContent`)
+---@param contents (table, optional, default `{}`) List of strings to extend with converted lines
+---@returns {contents}, extended with lines of converted markdown.
+---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
 function M.convert_input_to_markdown_lines(input, contents)
   contents = contents or {}
   -- MarkedString variation 1
@@ -844,11 +844,11 @@ end
 
 --- Converts `textDocument/SignatureHelp` response to markdown lines.
 ---
---@param signature_help Response of `textDocument/SignatureHelp`
---@param ft optional filetype that will be use as the `lang` for the label markdown code block
---@param triggers optional list of trigger characters from the lsp server. used to better determine parameter offsets
---@returns list of lines of converted markdown.
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp
+---@param signature_help Response of `textDocument/SignatureHelp`
+---@param ft optional filetype that will be use as the `lang` for the label markdown code block
+---@param triggers optional list of trigger characters from the lsp server. used to better determine parameter offsets
+---@returns list of lines of converted markdown.
+---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp
 function M.convert_signature_help_to_markdown_lines(signature_help, ft, triggers)
   if not signature_help.signatures then
     return
@@ -943,10 +943,10 @@ end
 --- Creates a table with sensible default options for a floating window. The
 --- table can be passed to |nvim_open_win()|.
 ---
---@param width (number) window width (in character cells)
---@param height (number) window height (in character cells)
---@param opts (table, optional)
---@returns (table) Options
+---@param width (number) window width (in character cells)
+---@param height (number) window height (in character cells)
+---@param opts (table, optional)
+---@returns (table) Options
 function M.make_floating_popup_options(width, height, opts)
   validate {
     opts = { opts, 't', true };
@@ -997,8 +997,8 @@ end
 
 --- Jumps to a location.
 ---
---@param location (`Location`|`LocationLink`)
---@returns `true` if the jump succeeded
+---@param location (`Location`|`LocationLink`)
+---@returns `true` if the jump succeeded
 function M.jump_to_location(location)
   -- location may be Location or LocationLink
   local uri = location.uri or location.targetUri
@@ -1028,8 +1028,8 @@ end
 ---   - for Location, range is shown (e.g., function definition)
 ---   - for LocationLink, targetRange is shown (e.g., body of function definition)
 ---
---@param location a single `Location` or `LocationLink`
---@returns (bufnr,winnr) buffer and window number of floating window or nil
+---@param location a single `Location` or `LocationLink`
+---@returns (bufnr,winnr) buffer and window number of floating window or nil
 function M.preview_location(location, opts)
   -- location may be LocationLink or Location (more useful for the former)
   local uri = location.targetUri or location.uri
@@ -1052,7 +1052,7 @@ function M.preview_location(location, opts)
   return M.open_floating_preview(contents, syntax, opts)
 end
 
---@private
+---@private
 local function find_window_by_var(name, value)
   for _, win in ipairs(api.nvim_list_wins()) do
     if npcall(api.nvim_win_get_var, win, name) == value then
@@ -1088,10 +1088,10 @@ function M._trim(contents, opts)
   return contents
 end
 
--- Generates a table mapping markdown code block lang to vim syntax,
--- based on g:markdown_fenced_languages
--- @return a table of lang -> syntax mappings
--- @private
+--- Generates a table mapping markdown code block lang to vim syntax,
+--- based on g:markdown_fenced_languages
+---@return a table of lang -> syntax mappings
+---@private
 local function get_markdown_fences()
   local fences = {}
   for _, fence in pairs(vim.g.markdown_fenced_languages or {}) do
@@ -1227,7 +1227,7 @@ function M.stylize_markdown(bufnr, contents, opts)
   vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, stripped)
 
   local idx = 1
-  --@private
+  ---@private
   -- keep track of syntaxes we already inlcuded.
   -- no need to include the same syntax more than once
   local langs = {}
@@ -1276,26 +1276,26 @@ end
 
 --- Creates autocommands to close a preview window when events happen.
 ---
---@param events (table) list of events
---@param winnr (number) window id of preview window
---@see |autocmd-events|
+---@param events (table) list of events
+---@param winnr (number) window id of preview window
+---@see |autocmd-events|
 function M.close_preview_autocmd(events, winnr)
   if #events > 0 then
     api.nvim_command("autocmd "..table.concat(events, ',').." <buffer> ++once lua pcall(vim.api.nvim_win_close, "..winnr..", true)")
   end
 end
 
---@internal
+---@internal
 --- Computes size of float needed to show contents (with optional wrapping)
 ---
---@param contents table of lines to show in window
---@param opts dictionary with optional fields
---             - height  of floating window
---             - width   of floating window
---             - wrap_at character to wrap at for computing height
---             - max_width  maximal width of floating window
---             - max_height maximal height of floating window
---@returns width,height size of float
+---@param contents table of lines to show in window
+---@param opts dictionary with optional fields
+---            - height  of floating window
+---            - width   of floating window
+---            - wrap_at character to wrap at for computing height
+---            - max_width  maximal width of floating window
+---            - max_height maximal height of floating window
+---@returns width,height size of float
 function M._make_floating_popup_size(contents, opts)
   validate {
     contents = { contents, 't' };
@@ -1362,9 +1362,9 @@ end
 
 --- Shows contents in a floating window.
 ---
---@param contents table of lines to show in window
---@param syntax string of syntax to set for opened buffer
---@param opts dictionary with optional fields
+---@param contents table of lines to show in window
+---@param syntax string of syntax to set for opened buffer
+---@param opts dictionary with optional fields
 ---             - height    of floating window
 ---             - width     of floating window
 ---             - wrap boolean enable wrapping of long lines (defaults to true)
@@ -1378,7 +1378,7 @@ end
 ---             - focus_id if a popup with this id is opened, then focus it
 ---             - close_events list of events that closes the floating window
 ---             - focusable (boolean, default true): Make float focusable
---@returns bufnr,winnr buffer and window number of the newly created floating
+---@returns bufnr,winnr buffer and window number of the newly created floating
 ---preview window
 function M.open_floating_preview(contents, syntax, opts)
   validate {
@@ -1474,7 +1474,7 @@ do --[[ References ]]
 
   --- Removes document highlights from a buffer.
   ---
-  --@param bufnr buffer id
+  ---@param bufnr buffer id
   function M.buf_clear_references(bufnr)
     validate { bufnr = {bufnr, 'n', true} }
     api.nvim_buf_clear_namespace(bufnr, reference_ns, 0, -1)
@@ -1482,8 +1482,8 @@ do --[[ References ]]
 
   --- Shows a list of document highlights for a certain buffer.
   ---
-  --@param bufnr buffer id
-  --@param references List of `DocumentHighlight` objects to highlight
+  ---@param bufnr buffer id
+  ---@param references List of `DocumentHighlight` objects to highlight
   ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#documentHighlight
   function M.buf_highlight_references(bufnr, references)
     validate { bufnr = {bufnr, 'n', true} }
@@ -1505,24 +1505,24 @@ local position_sort = sort_by_key(function(v)
   return {v.start.line, v.start.character}
 end)
 
--- Gets the zero-indexed line from the given uri.
+--- Gets the zero-indexed line from the given uri.
+---@param uri string uri of the resource to get the line from
+---@param row number zero-indexed line number
+---@return string the line at row in filename
 -- For non-file uris, we load the buffer and get the line.
 -- If a loaded buffer exists, then that is used.
 -- Otherwise we get the line using libuv which is a lot faster than loading the buffer.
---@param uri string uri of the resource to get the line from
---@param row number zero-indexed line number
---@return string the line at row in filename
 function M.get_line(uri, row)
   return M.get_lines(uri, { row })[row]
 end
 
--- Gets the zero-indexed lines from the given uri.
+--- Gets the zero-indexed lines from the given uri.
+---@param uri string uri of the resource to get the lines from
+---@param rows number[] zero-indexed line numbers
+---@return table<number string> a table mapping rows to lines
 -- For non-file uris, we load the buffer and get the lines.
 -- If a loaded buffer exists, then that is used.
 -- Otherwise we get the lines using libuv which is a lot faster than loading the buffer.
---@param uri string uri of the resource to get the lines from
---@param rows number[] zero-indexed line numbers
---@return table<number string> a table mapping rows to lines
 function M.get_lines(uri, rows)
   rows = type(rows) == "table" and rows or { rows }
 
@@ -1590,8 +1590,8 @@ end
 --- Returns the items with the byte position calculated correctly and in sorted
 --- order, for display in quickfix and location lists.
 ---
---@param locations (table) list of `Location`s or `LocationLink`s
---@returns (table) list of items
+---@param locations (table) list of `Location`s or `LocationLink`s
+---@returns (table) list of items
 function M.locations_to_items(locations)
   local items = {}
   local grouped = setmetatable({}, {
@@ -1648,7 +1648,7 @@ end
 --- Can be obtained with e.g. |vim.lsp.util.locations_to_items()|.
 --- Defaults to current window.
 ---
---@param items (table) list of items
+---@param items (table) list of items
 function M.set_loclist(items, win_id)
   vim.fn.setloclist(win_id or 0, {}, ' ', {
     title = 'Language Server';
@@ -1659,7 +1659,7 @@ end
 --- Fills quickfix list with given list of items.
 --- Can be obtained with e.g. |vim.lsp.util.locations_to_items()|.
 ---
---@param items (table) list of items
+---@param items (table) list of items
 function M.set_qflist(items)
   vim.fn.setqflist({}, ' ', {
     title = 'Language Server';
@@ -1676,9 +1676,9 @@ end
 
 --- Converts symbols to quickfix list items.
 ---
---@param symbols DocumentSymbol[] or SymbolInformation[]
+---@param symbols DocumentSymbol[] or SymbolInformation[]
 function M.symbols_to_items(symbols, bufnr)
-  --@private
+  ---@private
   local function _symbols_to_items(_symbols, _items, _bufnr)
     for _, symbol in ipairs(_symbols) do
       if symbol.location then -- SymbolInformation type
@@ -1714,8 +1714,8 @@ function M.symbols_to_items(symbols, bufnr)
 end
 
 --- Removes empty lines from the beginning and end.
---@param lines (table) list of lines to trim
---@returns (table) trimmed list of lines
+---@param lines (table) list of lines to trim
+---@returns (table) trimmed list of lines
 function M.trim_empty_lines(lines)
   local start = 1
   for i = 1, #lines do
@@ -1739,8 +1739,8 @@ end
 ---
 --- CAUTION: Modifies the input in-place!
 ---
---@param lines (table) list of lines
---@returns (string) filetype or 'markdown' if it was unchanged.
+---@param lines (table) list of lines
+---@returns (string) filetype or 'markdown' if it was unchanged.
 function M.try_trim_markdown_code_blocks(lines)
   local language_id = lines[1]:match("^```(.*)")
   if language_id then
@@ -1763,7 +1763,7 @@ function M.try_trim_markdown_code_blocks(lines)
 end
 
 local str_utfindex = vim.str_utfindex
---@private
+---@private
 local function make_position_param()
   local row, col = unpack(api.nvim_win_get_cursor(0))
   row = row - 1
@@ -1777,8 +1777,8 @@ end
 
 --- Creates a `TextDocumentPositionParams` object for the current buffer and cursor position.
 ---
---@returns `TextDocumentPositionParams` object
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams
+---@returns `TextDocumentPositionParams` object
+---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams
 function M.make_position_params()
   return {
     textDocument = M.make_text_document_params();
@@ -1791,7 +1791,7 @@ end
 --- `textDocument/codeAction`, `textDocument/colorPresentation`,
 --- `textDocument/rangeFormatting`.
 ---
---@returns { textDocument = { uri = `current_file_uri` }, range = { start =
+---@returns { textDocument = { uri = `current_file_uri` }, range = { start =
 ---`current_position`, end = `current_position` } }
 function M.make_range_params()
   local position = make_position_param()
@@ -1804,11 +1804,11 @@ end
 --- Using the given range in the current buffer, creates an object that
 --- is similar to |vim.lsp.util.make_range_params()|.
 ---
---@param start_pos ({number, number}, optional) mark-indexed position.
+---@param start_pos ({number, number}, optional) mark-indexed position.
 ---Defaults to the start of the last visual selection.
---@param end_pos ({number, number}, optional) mark-indexed position.
+---@param end_pos ({number, number}, optional) mark-indexed position.
 ---Defaults to the end of the last visual selection.
---@returns { textDocument = { uri = `current_file_uri` }, range = { start =
+---@returns { textDocument = { uri = `current_file_uri` }, range = { start =
 ---`start_position`, end = `end_position` } }
 function M.make_given_range_params(start_pos, end_pos)
   validate {
@@ -1844,23 +1844,23 @@ end
 
 --- Creates a `TextDocumentIdentifier` object for the current buffer.
 ---
---@returns `TextDocumentIdentifier`
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentIdentifier
+---@returns `TextDocumentIdentifier`
+---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentIdentifier
 function M.make_text_document_params()
   return { uri = vim.uri_from_bufnr(0) }
 end
 
 --- Create the workspace params
---@param added
---@param removed
+---@param added
+---@param removed
 function M.make_workspace_params(added, removed)
   return { event = { added = added; removed = removed; } }
 end
 --- Returns visual width of tabstop.
 ---
---@see |softtabstop|
---@param bufnr (optional, number): Buffer handle, defaults to current
---@returns (number) tabstop visual width
+---@see |softtabstop|
+---@param bufnr (optional, number): Buffer handle, defaults to current
+---@returns (number) tabstop visual width
 function M.get_effective_tabstop(bufnr)
   validate { bufnr = {bufnr, 'n', true} }
   local bo = bufnr and vim.bo[bufnr] or vim.bo
@@ -1870,9 +1870,9 @@ end
 
 --- Creates a `DocumentFormattingParams` object for the current buffer and cursor position.
 ---
---@param options Table with valid `FormattingOptions` entries
---@returns `DocumentFormattingParams` object
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting
+---@param options Table with valid `FormattingOptions` entries
+---@returns `DocumentFormattingParams` object
+---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting
 function M.make_formatting_params(options)
   validate { options = {options, 't', true} }
   options = vim.tbl_extend('keep', options or {}, {
@@ -1887,10 +1887,10 @@ end
 
 --- Returns the UTF-32 and UTF-16 offsets for a position in a certain buffer.
 ---
---@param buf buffer id (0 for current)
---@param row 0-indexed line
---@param col 0-indexed byte offset in line
---@returns (number, number) UTF-32 and UTF-16 index of the character in line {row} column {col} in buffer {buf}
+---@param buf buffer id (0 for current)
+---@param row 0-indexed line
+---@param col 0-indexed byte offset in line
+---@returns (number, number) UTF-32 and UTF-16 index of the character in line {row} column {col} in buffer {buf}
 function M.character_offset(bufnr, row, col)
   local uri = vim.uri_from_bufnr(bufnr)
   local line = M.get_line(uri, row)
@@ -1903,9 +1903,9 @@ end
 
 --- Helper function to return nested values in language server settings
 ---
---@param settings a table of language server settings
---@param section  a string indicating the field of the settings table
---@returns (table or string) The value of settings accessed via section
+---@param settings a table of language server settings
+---@param section  a string indicating the field of the settings table
+---@returns (table or string) The value of settings accessed via section
 function M.lookup_section(settings, section)
   for part in vim.gsplit(section, '.', true) do
     settings = settings[part]
@@ -1920,10 +1920,10 @@ end
 --- Convert diagnostics grouped by bufnr to a list of items for use in the
 --- quickfix or location list.
 ---
---@param diagnostics_by_bufnr table bufnr -> Diagnostic[]
---@param predicate an optional function to filter the diagnostics.
---                  If present, only diagnostic items matching will be included.
---@return table (A list of items)
+---@param diagnostics_by_bufnr table bufnr -> Diagnostic[]
+---@param predicate an optional function to filter the diagnostics.
+---                 If present, only diagnostic items matching will be included.
+---@return table (A list of items)
 function M.diagnostics_to_items(diagnostics_by_bufnr, predicate)
   local items = {}
   for bufnr, diagnostics in pairs(diagnostics_by_bufnr or {}) do
diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 33c2b2c46c..032b2b2cb5 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -12,8 +12,8 @@ local vim = vim or {}
 --- same functions as those in the input table. Userdata and threads are not
 --- copied and will throw an error.
 ---
---@param orig Table to copy
---@returns New table of copied keys and (nested) values.
+---@param orig Table to copy
+---@returns New table of copied keys and (nested) values.
 function vim.deepcopy(orig) end  -- luacheck: no unused
 vim.deepcopy = (function()
   local function _id(v)
@@ -52,14 +52,14 @@ end)()
 
 --- Splits a string at each instance of a separator.
 ---
---@see |vim.split()|
---@see https://www.lua.org/pil/20.2.html
---@see http://lua-users.org/wiki/StringLibraryTutorial
+---@see |vim.split()|
+---@see https://www.lua.org/pil/20.2.html
+---@see http://lua-users.org/wiki/StringLibraryTutorial
 ---
---@param s String to split
---@param sep Separator string or pattern
---@param plain If `true` use `sep` literally (passed to String.find)
---@returns Iterator over the split components
+---@param s String to split
+---@param sep Separator string or pattern
+---@param plain If `true` use `sep` literally (passed to String.find)
+---@returns Iterator over the split components
 function vim.gsplit(s, sep, plain)
   vim.validate{s={s,'s'},sep={sep,'s'},plain={plain,'b',true}}
 
@@ -101,12 +101,12 @@ end
 ---  split(x*yz*o, "*", true)  --> {'x','yz','o'}
 --- </pre>
 --
---@see |vim.gsplit()|
+---@see |vim.gsplit()|
 ---
---@param s String to split
---@param sep Separator string or pattern
---@param plain If `true` use `sep` literally (passed to String.find)
---@returns List-like table of the split components.
+---@param s String to split
+---@param sep Separator string or pattern
+---@param plain If `true` use `sep` literally (passed to String.find)
+---@returns List-like table of the split components.
 function vim.split(s,sep,plain)
   local t={} for c in vim.gsplit(s, sep, plain) do table.insert(t,c) end
   return t
@@ -115,10 +115,10 @@ end
 --- Return a list of all keys used in a table.
 --- However, the order of the return table of keys is not guaranteed.
 ---
---@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
+---@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
 ---
---@param t Table
---@returns list of keys
+---@param t Table
+---@returns list of keys
 function vim.tbl_keys(t)
   assert(type(t) == 'table', string.format("Expected table, got %s", type(t)))
 
@@ -132,8 +132,8 @@ end
 --- Return a list of all values used in a table.
 --- However, the order of the return table of values is not guaranteed.
 ---
---@param t Table
---@returns list of values
+---@param t Table
+---@returns list of values
 function vim.tbl_values(t)
   assert(type(t) == 'table', string.format("Expected table, got %s", type(t)))
 
@@ -146,8 +146,8 @@ end
 
 --- Apply a function to all values of a table.
 ---
---@param func function or callable table
---@param t table
+---@param func function or callable table
+---@param t table
 function vim.tbl_map(func, t)
   vim.validate{func={func,'c'},t={t,'t'}}
 
@@ -160,8 +160,8 @@ end
 
 --- Filter a table using a predicate function
 ---
---@param func function or callable table
---@param t table
+---@param func function or callable table
+---@param t table
 function vim.tbl_filter(func, t)
   vim.validate{func={func,'c'},t={t,'t'}}
 
@@ -176,9 +176,9 @@ end
 
 --- Checks if a list-like (vector) table contains `value`.
 ---
---@param t Table to check
---@param value Value to compare
---@returns true if `t` contains `value`
+---@param t Table to check
+---@param value Value to compare
+---@returns true if `t` contains `value`
 function vim.tbl_contains(t, value)
   vim.validate{t={t,'t'}}
 
@@ -192,16 +192,16 @@ end
 
 --- Checks if a table is empty.
 ---
---@see https://github.com/premake/premake-core/blob/master/src/base/table.lua
+---@see https://github.com/premake/premake-core/blob/master/src/base/table.lua
 ---
---@param t Table to check
+---@param t Table to check
 function vim.tbl_isempty(t)
   assert(type(t) == 'table', string.format("Expected table, got %s", type(t)))
   return next(t) == nil
 end
 
 --- we only merge empty tables or tables that are not a list
---@private
+---@private
 local function can_merge(v)
   return type(v) == "table" and (vim.tbl_isempty(v) or not vim.tbl_islist(v))
 end
@@ -242,26 +242,26 @@ end
 
 --- Merges two or more map-like tables.
 ---
---@see |extend()|
+---@see |extend()|
 ---
---@param behavior Decides what to do if a key is found in more than one map:
+---@param behavior Decides what to do if a key is found in more than one map:
 ---      - "error": raise an error
 ---      - "keep":  use value from the leftmost map
 ---      - "force": use value from the rightmost map
---@param ... Two or more map-like tables.
+---@param ... Two or more map-like tables.
 function vim.tbl_extend(behavior, ...)
   return tbl_extend(behavior, false, ...)
 end
 
 --- Merges recursively two or more map-like tables.
 ---
---@see |tbl_extend()|
+---@see |tbl_extend()|
 ---
---@param behavior Decides what to do if a key is found in more than one map:
+---@param behavior Decides what to do if a key is found in more than one map:
 ---      - "error": raise an error
 ---      - "keep":  use value from the leftmost map
 ---      - "force": use value from the rightmost map
---@param ... Two or more map-like tables.
+---@param ... Two or more map-like tables.
 function vim.tbl_deep_extend(behavior, ...)
   return tbl_extend(behavior, true, ...)
 end
@@ -292,7 +292,7 @@ end
 --- `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = 1 }`
 --
 --Do note that it *modifies* the input.
---@param o table The table to add the reverse to.
+---@param o table The table to add the reverse to.
 function vim.tbl_add_reverse_lookup(o)
   local keys = vim.tbl_keys(o)
   for _, k in ipairs(keys) do
@@ -309,13 +309,13 @@ end
 ---
 --- NOTE: This mutates dst!
 ---
---@see |vim.tbl_extend()|
+---@see |vim.tbl_extend()|
 ---
---@param dst list which will be modified and appended to.
---@param src list from which values will be inserted.
---@param start Start index on src. defaults to 1
---@param finish Final index on src. defaults to #src
---@returns dst
+---@param dst list which will be modified and appended to.
+---@param src list from which values will be inserted.
+---@param start Start index on src. defaults to 1
+---@param finish Final index on src. defaults to #src
+---@returns dst
 function vim.list_extend(dst, src, start, finish)
   vim.validate {
     dst = {dst, 't'};
@@ -332,10 +332,10 @@ end
 --- Creates a copy of a list-like table such that any nested tables are
 --- "unrolled" and appended to the result.
 ---
---@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
+---@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
 ---
---@param t List-like table
---@returns Flattened copy of the given list-like table.
+---@param t List-like table
+---@returns Flattened copy of the given list-like table.
 function vim.tbl_flatten(t)
   local result = {}
   local function _tbl_flatten(_t)
@@ -359,8 +359,8 @@ end
 --- |vim.empty_dict()| or returned as a dict-like |API| or Vimscript result,
 --- for example from |rpcrequest()| or |vim.fn|.
 ---
---@param t Table
---@returns `true` if array-like table, else `false`.
+---@param t Table
+---@returns `true` if array-like table, else `false`.
 function vim.tbl_islist(t)
   if type(t) ~= 'table' then
     return false
@@ -395,9 +395,9 @@ end
 --- vim.tbl_count({ 1, 2 }) => 2
 --- </pre>
 ---
---@see https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua
---@param t Table
---@returns Number that is the number of the value in table
+---@see https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua
+---@param t Table
+---@returns Number that is the number of the value in table
 function vim.tbl_count(t)
   vim.validate{t={t,'t'}}
 
@@ -408,10 +408,10 @@ end
 
 --- Creates a copy of a table containing only elements from start to end (inclusive)
 ---
---@param list table table
---@param start integer Start range of slice
---@param finish integer End range of slice
---@returns Copy of table sliced from start to finish (inclusive)
+---@param list table table
+---@param start integer Start range of slice
+---@param finish integer End range of slice
+---@returns Copy of table sliced from start to finish (inclusive)
 function vim.list_slice(list, start, finish)
   local new_list = {}
   for i = start or 1, finish or #list do
@@ -422,9 +422,9 @@ end
 
 --- Trim whitespace (Lua pattern "%s") from both sides of a string.
 ---
---@see https://www.lua.org/pil/20.2.html
---@param s String to trim
---@returns String with whitespace removed from its beginning and end
+---@see https://www.lua.org/pil/20.2.html
+---@param s String to trim
+---@returns String with whitespace removed from its beginning and end
 function vim.trim(s)
   vim.validate{s={s,'s'}}
   return s:match('^%s*(.*%S)') or ''
@@ -432,9 +432,9 @@ end
 
 --- Escapes magic chars in a Lua pattern.
 ---
---@see https://github.com/rxi/lume
---@param s  String to escape
---@returns  %-escaped pattern string
+---@see https://github.com/rxi/lume
+---@param s  String to escape
+---@returns  %-escaped pattern string
 function vim.pesc(s)
   vim.validate{s={s,'s'}}
   return s:gsub('[%(%)%.%%%+%-%*%?%[%]%^%$]', '%%%1')
@@ -442,9 +442,9 @@ end
 
 --- Tests if `s` starts with `prefix`.
 ---
---@param s (string) a string
---@param prefix (string) a prefix
---@return (boolean) true if `prefix` is a prefix of s
+---@param s (string) a string
+---@param prefix (string) a prefix
+---@return (boolean) true if `prefix` is a prefix of s
 function vim.startswith(s, prefix)
   vim.validate { s = {s, 's'}; prefix = {prefix, 's'}; }
   return s:sub(1, #prefix) == prefix
@@ -452,9 +452,9 @@ end
 
 --- Tests if `s` ends with `suffix`.
 ---
---@param s (string) a string
---@param suffix (string) a suffix
---@return (boolean) true if `suffix` is a suffix of s
+---@param s (string) a string
+---@param suffix (string) a suffix
+---@return (boolean) true if `suffix` is a suffix of s
 function vim.endswith(s, suffix)
   vim.validate { s = {s, 's'}; suffix = {suffix, 's'}; }
   return #suffix == 0 or s:sub(-#suffix) == suffix
@@ -486,7 +486,7 @@ end
 ---     => error('arg1: expected even number, got 3')
 --- </pre>
 ---
---@param opt Map of parameter names to validations. Each key is a parameter
+---@param opt Map of parameter names to validations. Each key is a parameter
 ---          name; each value is a tuple in one of these forms:
 ---          1. (arg_value, type_name, optional)
 ---             - arg_value: argument value
@@ -570,8 +570,8 @@ do
 end
 --- Returns true if object `f` can be called as a function.
 ---
---@param f Any object
---@return true if `f` is callable, else false
+---@param f Any object
+---@return true if `f` is callable, else false
 function vim.is_callable(f)
   if type(f) == 'function' then return true end
   local m = getmetatable(f)
diff --git a/runtime/lua/vim/treesitter.lua b/runtime/lua/vim/treesitter.lua
index de997b2d86..a09e0a9cf7 100644
--- a/runtime/lua/vim/treesitter.lua
+++ b/runtime/lua/vim/treesitter.lua
@@ -28,9 +28,9 @@ setmetatable(M, {
 ---
 --- It is not recommended to use this, use vim.treesitter.get_parser() instead.
 ---
---- @param bufnr The buffer the parser will be tied to
---- @param lang The language of the parser
---- @param opts Options to pass to the created language tree
+---@param bufnr The buffer the parser will be tied to
+---@param lang The language of the parser
+---@param opts Options to pass to the created language tree
 function M._create_parser(bufnr, lang, opts)
   language.require_language(lang)
   if bufnr == 0 then
@@ -71,11 +71,11 @@ end
 --- If needed this will create the parser.
 --- Unconditionnally attach the provided callback
 ---
---- @param bufnr The buffer the parser should be tied to
---- @param lang The filetype of this parser
---- @param opts Options object to pass to the created language tree
+---@param bufnr The buffer the parser should be tied to
+---@param lang The filetype of this parser
+---@param opts Options object to pass to the created language tree
 ---
---- @returns The parser
+---@returns The parser
 function M.get_parser(bufnr, lang, opts)
   opts = opts or {}
 
@@ -97,9 +97,9 @@ end
 
 --- Gets a string parser
 ---
---- @param str The string to parse
---- @param lang The language of this string
---- @param opts Options to pass to the created language tree
+---@param str The string to parse
+---@param lang The language of this string
+---@param opts Options to pass to the created language tree
 function M.get_string_parser(str, lang, opts)
   vim.validate {
     str = { str, 'string' },
diff --git a/runtime/lua/vim/treesitter/highlighter.lua b/runtime/lua/vim/treesitter/highlighter.lua
index bf5bd791c3..22b528838c 100644
--- a/runtime/lua/vim/treesitter/highlighter.lua
+++ b/runtime/lua/vim/treesitter/highlighter.lua
@@ -122,8 +122,8 @@ end
 
 --- Creates a new highlighter using @param tree
 ---
---- @param tree The language tree to use for highlighting
---- @param opts Table used to configure the highlighter
+---@param tree The language tree to use for highlighting
+---@param opts Table used to configure the highlighter
 ---           - queries: Table to overwrite queries used by the highlighter
 function TSHighlighter.new(tree, opts)
   local self = setmetatable({}, TSHighlighter)
@@ -217,7 +217,7 @@ end
 
 --- Gets the query used for @param lang
 ---
---- @param lang A language used by the highlighter.
+---@param lang A language used by the highlighter.
 function TSHighlighter:get_query(lang)
   if not self._queries[lang] then
     self._queries[lang] = TSHighlighterQuery.new(lang)
diff --git a/runtime/lua/vim/treesitter/language.lua b/runtime/lua/vim/treesitter/language.lua
index 6dc37c7848..89ddd6cd5a 100644
--- a/runtime/lua/vim/treesitter/language.lua
+++ b/runtime/lua/vim/treesitter/language.lua
@@ -6,9 +6,9 @@ local M = {}
 ---
 --- Parsers are searched in the `parser` runtime directory.
 ---
---- @param lang The language the parser should parse
---- @param path Optional path the parser is located at
---- @param silent Don't throw an error if language not found
+---@param lang The language the parser should parse
+---@param path Optional path the parser is located at
+---@param silent Don't throw an error if language not found
 function M.require_language(lang, path, silent)
   if vim._ts_has_language(lang) then
     return true
@@ -40,7 +40,7 @@ end
 ---
 --- Inspecting provides some useful informations on the language like node names, ...
 ---
---- @param lang The language.
+---@param lang The language.
 function M.inspect_language(lang)
   M.require_language(lang)
   return vim._ts_inspect_language(lang)
diff --git a/runtime/lua/vim/treesitter/languagetree.lua b/runtime/lua/vim/treesitter/languagetree.lua
index 899d90e464..7e392f72a4 100644
--- a/runtime/lua/vim/treesitter/languagetree.lua
+++ b/runtime/lua/vim/treesitter/languagetree.lua
@@ -9,12 +9,12 @@ LanguageTree.__index = LanguageTree
 --- The language can contain child languages with in its range,
 --- hence the tree.
 ---
---- @param source Can be a bufnr or a string of text to parse
---- @param lang The language this tree represents
---- @param opts Options table
---- @param opts.injections A table of language to injection query strings.
----                        This is useful for overriding the built-in runtime file
----                        searching for the injection language query per language.
+---@param source Can be a bufnr or a string of text to parse
+---@param lang The language this tree represents
+---@param opts Options table
+---@param opts.injections A table of language to injection query strings.
+---                      This is useful for overriding the built-in runtime file
+---                      searching for the injection language query per language.
 function LanguageTree.new(source, lang, opts)
   language.require_language(lang)
   opts = opts or {}
@@ -171,8 +171,8 @@ end
 
 --- Invokes the callback for each LanguageTree and it's children recursively
 ---
---- @param fn The function to invoke. This is invoked with arguments (tree: LanguageTree, lang: string)
---- @param include_self Whether to include the invoking tree in the results.
+---@param fn The function to invoke. This is invoked with arguments (tree: LanguageTree, lang: string)
+---@param include_self Whether to include the invoking tree in the results.
 function LanguageTree:for_each_child(fn, include_self)
   if include_self then
     fn(self, self._lang)
@@ -187,8 +187,8 @@ end
 ---
 --- Note, this includes the invoking language tree's trees as well.
 ---
---- @param fn The callback to invoke. The callback is invoked with arguments
----           (tree: TSTree, languageTree: LanguageTree)
+---@param fn The callback to invoke. The callback is invoked with arguments
+---         (tree: TSTree, languageTree: LanguageTree)
 function LanguageTree:for_each_tree(fn)
   for _, tree in ipairs(self._trees) do
     fn(tree, self)
@@ -203,7 +203,7 @@ end
 ---
 --- If the language already exists as a child, it will first be removed.
 ---
---- @param lang The language to add.
+---@param lang The language to add.
 function LanguageTree:add_child(lang)
   if self._children[lang] then
     self:remove_child(lang)
@@ -219,7 +219,7 @@ end
 
 --- Removes a child language from this tree.
 ---
---- @param lang The language to remove.
+---@param lang The language to remove.
 function LanguageTree:remove_child(lang)
   local child = self._children[lang]
 
@@ -259,7 +259,7 @@ end
 ---
 --- Note, this call invalidates the tree and requires it to be parsed again.
 ---
---- @param regions A list of regions this tree should manage and parse.
+---@param regions A list of regions this tree should manage and parse.
 function LanguageTree:set_included_regions(regions)
   -- TODO(vigoux): I don't think string parsers are useful for now
   if type(self._source) == "number" then
@@ -299,7 +299,7 @@ end
 ---
 --- TODO: Allow for an offset predicate to tailor the injection range
 ---       instead of using the entire nodes range.
---- @private
+---@private
 function LanguageTree:_get_injections()
   if not self._injection_query then return {} end
 
@@ -449,7 +449,7 @@ function LanguageTree:_on_detach(...)
 end
 
 --- Registers callbacks for the parser
---- @param cbs An `nvim_buf_attach`-like table argument with the following keys :
+---@param cbs An `nvim_buf_attach`-like table argument with the following keys :
 ---  `on_bytes` : see `nvim_buf_attach`, but this will be called _after_ the parsers callback.
 ---  `on_changedtree` : a callback that will be called every time the tree has syntactical changes.
 ---      it will only be passed one argument, that is a table of the ranges (as node ranges) that
@@ -497,7 +497,7 @@ end
 ---
 --- This goes down the tree to recursively check childs.
 ---
---- @param range A range, that is a `{ start_line, start_col, end_line, end_col }` table.
+---@param range A range, that is a `{ start_line, start_col, end_line, end_col }` table.
 function LanguageTree:contains(range)
   for _, tree in pairs(self._trees) do
     if tree_contains(tree, range) then
@@ -510,7 +510,7 @@ end
 
 --- Gets the appropriate language that contains @param range
 ---
---- @param range A text range, see |LanguageTree:contains|
+---@param range A text range, see |LanguageTree:contains|
 function LanguageTree:language_for_range(range)
   for _, child in pairs(self._children) do
     if child:contains(range) then
diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua
index 4ecd91d295..66da179ea3 100644
--- a/runtime/lua/vim/treesitter/query.lua
+++ b/runtime/lua/vim/treesitter/query.lua
@@ -36,9 +36,9 @@ end
 
 --- Gets the list of files used to make up a query
 ---
---- @param lang The language
---- @param query_name The name of the query to load
---- @param is_included Internal parameter, most of the time left as `nil`
+---@param lang The language
+---@param query_name The name of the query to load
+---@param is_included Internal parameter, most of the time left as `nil`
 function M.get_query_files(lang, query_name, is_included)
   local query_path = string.format('queries/%s/%s.scm', lang, query_name)
   local lang_files = dedupe_files(a.nvim_get_runtime_file(query_path, true))
@@ -112,19 +112,19 @@ local explicit_queries = setmetatable({}, {
 --- This allows users to override any runtime files and/or configuration
 --- set by plugins.
 ---
---- @param lang string: The language to use for the query
---- @param query_name string: The name of the query (i.e. "highlights")
---- @param text string: The query text (unparsed).
+---@param lang string: The language to use for the query
+---@param query_name string: The name of the query (i.e. "highlights")
+---@param text string: The query text (unparsed).
 function M.set_query(lang, query_name, text)
   explicit_queries[lang][query_name] = M.parse_query(lang, text)
 end
 
 --- Returns the runtime query {query_name} for {lang}.
 ---
---- @param lang The language to use for the query
---- @param query_name The name of the query (i.e. "highlights")
+---@param lang The language to use for the query
+---@param query_name The name of the query (i.e. "highlights")
 ---
---- @return The corresponding query, parsed.
+---@return The corresponding query, parsed.
 function M.get_query(lang, query_name)
   if explicit_queries[lang][query_name] then
     return explicit_queries[lang][query_name]
@@ -151,10 +151,10 @@ end
 ---   -` info.captures` also points to `captures`.
 ---   - `info.patterns` contains information about predicates.
 ---
---- @param lang The language
---- @param query A string containing the query (s-expr syntax)
+---@param lang The language
+---@param query A string containing the query (s-expr syntax)
 ---
---- @returns The query
+---@returns The query
 function M.parse_query(lang, query)
   language.require_language(lang)
   local self = setmetatable({}, Query)
@@ -168,8 +168,8 @@ end
 
 --- Gets the text corresponding to a given node
 ---
---- @param node the node
---- @param bsource The buffer or string from which the node is extracted
+---@param node the node
+---@param bsource The buffer or string from which the node is extracted
 function M.get_node_text(node, source)
   local start_row, start_col, start_byte = node:start()
   local end_row, end_col, end_byte = node:end_()
@@ -327,9 +327,9 @@ local directive_handlers = {
 
 --- Adds a new predicate to be used in queries
 ---
---- @param name the name of the predicate, without leading #
---- @param handler the handler function to be used
----    signature will be (match, pattern, bufnr, predicate)
+---@param name the name of the predicate, without leading #
+---@param handler the handler function to be used
+---      signature will be (match, pattern, bufnr, predicate)
 function M.add_predicate(name, handler, force)
   if predicate_handlers[name] and not force then
     error(string.format("Overriding %s", name))
@@ -340,9 +340,9 @@ end
 
 --- Adds a new directive to be used in queries
 ---
---- @param name the name of the directive, without leading #
---- @param handler the handler function to be used
----    signature will be (match, pattern, bufnr, predicate)
+---@param name the name of the directive, without leading #
+---@param handler the handler function to be used
+---      signature will be (match, pattern, bufnr, predicate)
 function M.add_directive(name, handler, force)
   if directive_handlers[name] and not force then
     error(string.format("Overriding %s", name))
@@ -351,12 +351,12 @@ function M.add_directive(name, handler, force)
   directive_handlers[name] = handler
 end
 
---- @return The list of supported directives.
+---@return The list of supported directives.
 function M.list_directives()
   return vim.tbl_keys(directive_handlers)
 end
 
---- @return The list of supported predicates.
+---@return The list of supported predicates.
 function M.list_predicates()
   return vim.tbl_keys(predicate_handlers)
 end
@@ -465,13 +465,13 @@ end
 --- end
 --- </pre>
 ---
---- @param node The node under which the search will occur
---- @param source The source buffer or string to exctract text from
---- @param start The starting line of the search
---- @param stop The stopping line of the search (end-exclusive)
+---@param node The node under which the search will occur
+---@param source The source buffer or string to exctract text from
+---@param start The starting line of the search
+---@param stop The stopping line of the search (end-exclusive)
 ---
---- @returns The matching capture id
---- @returns The captured node
+---@returns The matching capture id
+---@returns The captured node
 function Query:iter_captures(node, source, start, stop)
   if type(source) == "number" and source == 0 then
     source = vim.api.nvim_get_current_buf()
@@ -522,13 +522,13 @@ end
 --- end
 --- </pre>
 ---
---- @param node The node under which the search will occur
---- @param source The source buffer or string to search
---- @param start The starting line of the search
---- @param stop The stopping line of the search (end-exclusive)
+---@param node The node under which the search will occur
+---@param source The source buffer or string to search
+---@param start The starting line of the search
+---@param stop The stopping line of the search (end-exclusive)
 ---
---- @returns The matching pattern id
---- @returns The matching match
+---@returns The matching pattern id
+---@returns The matching match
 function Query:iter_matches(node, source, start, stop)
   if type(source) == "number" and source == 0 then
     source = vim.api.nvim_get_current_buf()
diff --git a/runtime/lua/vim/uri.lua b/runtime/lua/vim/uri.lua
index 82c9a31464..a3e79a0f2b 100644
--- a/runtime/lua/vim/uri.lua
+++ b/runtime/lua/vim/uri.lua
@@ -9,7 +9,7 @@ do
   local schar = string.char
 
   --- Convert hex to char
-  --@private
+  ---@private
   local function hex_to_char(hex)
     return schar(tonumber(hex, 16))
   end
@@ -38,7 +38,7 @@ do
     tohex = function(b) return string.format("%02x", b) end
   end
 
-  --@private
+  ---@private
   local function percent_encode_char(char)
     return "%"..tohex(sbyte(char), 2)
   end
@@ -50,14 +50,14 @@ do
 end
 
 
---@private
+---@private
 local function is_windows_file_uri(uri)
   return uri:match('^file:/+[a-zA-Z]:') ~= nil
 end
 
 --- Get a URI from a file path.
---@param path (string): Path to file
---@return URI
+---@param path (string): Path to file
+---@return URI
 local function uri_from_fname(path)
   local volume_path, fname = path:match("^([a-zA-Z]:)(.*)")
   local is_windows = volume_path ~= nil
@@ -77,8 +77,8 @@ end
 local URI_SCHEME_PATTERN = '^([a-zA-Z]+[a-zA-Z0-9+-.]*):.*'
 
 --- Get a URI from a bufnr
---@param bufnr (number): Buffer number
---@return URI
+---@param bufnr (number): Buffer number
+---@return URI
 local function uri_from_bufnr(bufnr)
   local fname = vim.api.nvim_buf_get_name(bufnr)
   local scheme = fname:match(URI_SCHEME_PATTERN)
@@ -90,8 +90,8 @@ local function uri_from_bufnr(bufnr)
 end
 
 --- Get a filename from a URI
---@param uri (string): The URI
---@return Filename
+---@param uri (string): The URI
+---@return Filename
 local function uri_to_fname(uri)
   local scheme = assert(uri:match(URI_SCHEME_PATTERN), 'URI must contain a scheme: ' .. uri)
   if scheme ~= 'file' then
@@ -109,9 +109,9 @@ local function uri_to_fname(uri)
 end
 
 --- Return or create a buffer for a uri.
---@param uri (string): The URI
---@return bufnr.
---@note Creates buffer but does not load it
+---@param uri (string): The URI
+---@return bufnr.
+---@note Creates buffer but does not load it
 local function uri_to_bufnr(uri)
   local scheme = assert(uri:match(URI_SCHEME_PATTERN), 'URI must contain a scheme: ' .. uri)
   if scheme == 'file' then
diff --git a/src/nvim/lua/vim.lua b/src/nvim/lua/vim.lua
index 8cecaa51dd..ed435439a4 100644
--- a/src/nvim/lua/vim.lua
+++ b/src/nvim/lua/vim.lua
@@ -178,8 +178,8 @@ end
 
 --- Return a human-readable representation of the given object.
 ---
---@see https://github.com/kikito/inspect.lua
---@see https://github.com/mpeterv/vinspect
+---@see https://github.com/kikito/inspect.lua
+---@see https://github.com/mpeterv/vinspect
 local function inspect(object, options)  -- luacheck: no unused
   error(object, options)  -- Stub for gen_vimdoc.py
 end
@@ -203,15 +203,15 @@ do
   --- end)(vim.paste)
   --- </pre>
   ---
-  --@see |paste|
+  ---@see |paste|
   ---
-  --@param lines  |readfile()|-style list of lines to paste. |channel-lines|
-  --@param phase  -1: "non-streaming" paste: the call contains all lines.
+  ---@param lines  |readfile()|-style list of lines to paste. |channel-lines|
+  ---@param phase  -1: "non-streaming" paste: the call contains all lines.
   ---              If paste is "streamed", `phase` indicates the stream state:
   ---                - 1: starts the paste (exactly once)
   ---                - 2: continues the paste (zero or more times)
   ---                - 3: ends the paste (exactly once)
-  --@returns false if client should cancel the paste.
+  ---@returns false if client should cancel the paste.
   function vim.paste(lines, phase)
     local call = vim.api.nvim_call_function
     local now = vim.loop.now()
@@ -279,7 +279,7 @@ function vim.schedule_wrap(cb)
 end
 
 --- <Docs described in |vim.empty_dict()| >
---@private
+---@private
 function vim.empty_dict()
   return setmetatable({}, vim._empty_dict_mt)
 end
@@ -338,12 +338,12 @@ end
 
 --- Get a table of lines with start, end columns for a region marked by two points
 ---
---@param bufnr number of buffer
---@param pos1 (line, column) tuple marking beginning of region
---@param pos2 (line, column) tuple marking end of region
---@param regtype type of selection (:help setreg)
---@param inclusive boolean indicating whether the selection is end-inclusive
---@return region lua table of the form {linenr = {startcol,endcol}}
+---@param bufnr number of buffer
+---@param pos1 (line, column) tuple marking beginning of region
+---@param pos2 (line, column) tuple marking end of region
+---@param regtype type of selection (:help setreg)
+---@param inclusive boolean indicating whether the selection is end-inclusive
+---@return region lua table of the form {linenr = {startcol,endcol}}
 function vim.region(bufnr, pos1, pos2, regtype, inclusive)
   if not vim.api.nvim_buf_is_loaded(bufnr) then
     vim.fn.bufload(bufnr)
@@ -390,9 +390,9 @@ end
 --- Use to do a one-shot timer that calls `fn`
 --- Note: The {fn} is |schedule_wrap|ped automatically, so API functions are
 --- safe to call.
---@param fn Callback to call once `timeout` expires
---@param timeout Number of milliseconds to wait before calling `fn`
---@return timer luv timer object
+---@param fn Callback to call once `timeout` expires
+---@param timeout Number of milliseconds to wait before calling `fn`
+---@return timer luv timer object
 function vim.defer_fn(fn, timeout)
   vim.validate { fn = { fn, 'c', true}; }
   local timer = vim.loop.new_timer()
@@ -408,11 +408,12 @@ end
 
 
 --- Notification provider
---- without a runtime, writes to :Messages
---  see :help nvim_notify
---@param msg Content of the notification to show to the user
---@param log_level Optional log level
---@param opts Dictionary with optional options (timeout, etc)
+---
+--- Without a runtime, writes to :Messages
+---@see :help nvim_notify
+---@param msg Content of the notification to show to the user
+---@param log_level Optional log level
+---@param opts Dictionary with optional options (timeout, etc)
 function vim.notify(msg, log_level, _opts)
 
   if log_level == vim.log.levels.ERROR then
@@ -429,21 +430,21 @@ local on_keystroke_callbacks = {}
 
 --- Register a lua {fn} with an {id} to be run after every keystroke.
 ---
---@param fn function: Function to call. It should take one argument, which is a string.
+---@param fn function: Function to call. It should take one argument, which is a string.
 ---                   The string will contain the literal keys typed.
 ---                   See |i_CTRL-V|
 ---
 ---                   If {fn} is nil, it removes the callback for the associated {ns_id}
---@param ns_id number? Namespace ID. If not passed or 0, will generate and return a new
+---@param ns_id number? Namespace ID. If not passed or 0, will generate and return a new
 ---                    namespace ID from |nvim_create_namesapce()|
 ---
---@return number Namespace ID associated with {fn}
+---@return number Namespace ID associated with {fn}
 ---
---@note {fn} will be automatically removed if an error occurs while calling.
+---@note {fn} will be automatically removed if an error occurs while calling.
 ---     This is to prevent the annoying situation of every keystroke erroring
 ---     while trying to remove a broken callback.
---@note {fn} will not be cleared from |nvim_buf_clear_namespace()|
---@note {fn} will receive the keystrokes after mappings have been evaluated
+---@note {fn} will not be cleared from |nvim_buf_clear_namespace()|
+---@note {fn} will receive the keystrokes after mappings have been evaluated
 function vim.register_keystroke_callback(fn, ns_id)
   vim.validate {
     fn = { fn, 'c', true},
@@ -459,7 +460,7 @@ function vim.register_keystroke_callback(fn, ns_id)
 end
 
 --- Function that executes the keystroke callbacks.
---@private
+---@private
 function vim._log_keystroke(char)
   local failed_ns_ids = {}
   local failed_messages = {}
diff --git a/test/functional/helpers.lua b/test/functional/helpers.lua
index 5974e8897f..92d802d62d 100644
--- a/test/functional/helpers.lua
+++ b/test/functional/helpers.lua
@@ -422,7 +422,7 @@ end
 
 -- Builds an argument list for use in clear().
 --
---@see clear() for parameters.
+---@see clear() for parameters.
 function module.new_argv(...)
   local args = {unpack(module.nvim_argv)}
   table.insert(args, '--headless')
@@ -573,7 +573,7 @@ function module.buf_lines(bufnr)
   return module.exec_lua("return vim.api.nvim_buf_get_lines((...), 0, -1, false)", bufnr)
 end
 
---@see buf_lines()
+---@see buf_lines()
 function module.curbuf_contents()
   module.poke_eventloop()  -- Before inspecting the buffer, do whatever.
   return table.concat(module.curbuf('get_lines', 0, -1, true), '\n')
diff --git a/test/helpers.lua b/test/helpers.lua
index 12d9f19187..469aee53f0 100644
--- a/test/helpers.lua
+++ b/test/helpers.lua
@@ -58,9 +58,9 @@ local check_logs_useless_lines = {
 --- Invokes `fn` and includes the tail of `logfile` in the error message if it
 --- fails.
 ---
---@param logfile  Log file, defaults to $NVIM_LOG_FILE or '.nvimlog'
---@param fn       Function to invoke
---@param ...      Function arguments
+---@param logfile  Log file, defaults to $NVIM_LOG_FILE or '.nvimlog'
+---@param fn       Function to invoke
+---@param ...      Function arguments
 local function dumplog(logfile, fn, ...)
   -- module.validate({
   --   logfile={logfile,'s',true},
@@ -102,8 +102,8 @@ end
 
 --- Asserts that `pat` matches one or more lines in the tail of $NVIM_LOG_FILE.
 ---
---@param pat  (string) Lua pattern to search for in the log file.
---@param logfile  (string, default=$NVIM_LOG_FILE) full path to log file.
+---@param pat  (string) Lua pattern to search for in the log file.
+---@param logfile  (string, default=$NVIM_LOG_FILE) full path to log file.
 function module.assert_log(pat, logfile)
   logfile = logfile or os.getenv('NVIM_LOG_FILE') or '.nvimlog'
   local nrlines = 10