docs: fix type warnings

6 files changed, 34 insertions, 25 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index ddf11fd966..a77cc3b565 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2752,7 +2752,7 @@ vim.keymap.del({modes}, {lhs}, {opts})                      *vim.keymap.del()*
 
     Parameters: ~
       • {opts}  (table|nil) A table of optional arguments:
-                • "buffer": (number|boolean) Remove a mapping from the given
+                • "buffer": (integer|boolean) Remove a mapping from the given
                   buffer. When `0` or `true`, use the current buffer.
 
     See also: ~
@@ -2786,7 +2786,7 @@ vim.keymap.set({mode}, {lhs}, {rhs}, {opts})                *vim.keymap.set()*
                   • "noremap": inverse of "remap" (see below).
 
                 • Also accepts:
-                  • "buffer": (number|boolean) Creates buffer-local mapping,
+                  • "buffer": (integer|boolean) Creates buffer-local mapping,
                     `0` or `true` for current buffer.
                   • "remap": (boolean) Make the mapping recursive. Inverse of
                     "noremap". Defaults to `false`.
diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua
index df593be097..bdea95f9ab 100644
--- a/runtime/lua/vim/keymap.lua
+++ b/runtime/lua/vim/keymap.lua
@@ -28,7 +28,7 @@ local keymap = {}
 ---                        - "replace_keycodes" defaults to `true` if "expr" is `true`.
 ---                        - "noremap": inverse of "remap" (see below).
 ---                      - Also accepts:
----                        - "buffer": (number|boolean) Creates buffer-local mapping, `0` or `true`
+---                        - "buffer": (integer|boolean) Creates buffer-local mapping, `0` or `true`
 ---                        for current buffer.
 ---                        - "remap": (boolean) Make the mapping recursive. Inverse of "noremap".
 ---                        Defaults to `false`.
@@ -44,7 +44,9 @@ function keymap.set(mode, lhs, rhs, opts)
     opts = { opts, 't', true },
   })
 
-  opts = vim.deepcopy(opts) or {}
+  opts = vim.deepcopy(opts or {})
+
+  ---@cast mode string[]
   mode = type(mode) == 'string' and { mode } or mode
 
   if opts.expr and opts.replace_keycodes ~= false then
@@ -57,7 +59,7 @@ function keymap.set(mode, lhs, rhs, opts)
   else
     -- remaps behavior is opposite of noremap option.
     opts.noremap = not opts.remap
-    opts.remap = nil
+    opts.remap = nil ---@type boolean?
   end
 
   if type(rhs) == 'function' then
@@ -66,8 +68,8 @@ function keymap.set(mode, lhs, rhs, opts)
   end
 
   if opts.buffer then
-    local bufnr = opts.buffer == true and 0 or opts.buffer
-    opts.buffer = nil
+    local bufnr = opts.buffer == true and 0 or opts.buffer --[[@as integer]]
+    opts.buffer = nil ---@type integer?
     for _, m in ipairs(mode) do
       vim.api.nvim_buf_set_keymap(bufnr, m, lhs, rhs, opts)
     end
@@ -89,7 +91,7 @@ end
 --- ```
 ---
 ---@param opts table|nil A table of optional arguments:
----                      - "buffer": (number|boolean) Remove a mapping from the given buffer.
+---                      - "buffer": (integer|boolean) Remove a mapping from the given buffer.
 ---                        When `0` or `true`, use the current buffer.
 ---@see |vim.keymap.set()|
 ---
@@ -103,9 +105,9 @@ function keymap.del(modes, lhs, opts)
   opts = opts or {}
   modes = type(modes) == 'string' and { modes } or modes
 
-  local buffer = false
+  local buffer = false ---@type false|integer
   if opts.buffer ~= nil then
-    buffer = opts.buffer == true and 0 or opts.buffer
+    buffer = opts.buffer == true and 0 or opts.buffer --[[@as integer]]
   end
 
   if buffer == false then
diff --git a/runtime/lua/vim/secure.lua b/runtime/lua/vim/secure.lua
index 893b3e1877..d29c356af3 100644
--- a/runtime/lua/vim/secure.lua
+++ b/runtime/lua/vim/secure.lua
@@ -2,9 +2,9 @@ local M = {}
 
 --- Reads trust database from $XDG_STATE_HOME/nvim/trust.
 ---
----@return (table) Contents of trust database, if it exists. Empty table otherwise.
+---@return table<string, string> Contents of trust database, if it exists. Empty table otherwise.
 local function read_trust()
-  local trust = {}
+  local trust = {} ---@type table<string, string>
   local f = io.open(vim.fn.stdpath('state') .. '/trust', 'r')
   if f then
     local contents = f:read('*a')
@@ -24,12 +24,12 @@ end
 --- Writes provided {trust} table to trust database at
 --- $XDG_STATE_HOME/nvim/trust.
 ---
----@param trust (table) Trust table to write
+---@param trust table<string, string> Trust table to write
 local function write_trust(trust)
   vim.validate({ trust = { trust, 't' } })
   local f = assert(io.open(vim.fn.stdpath('state') .. '/trust', 'w'))
 
-  local t = {}
+  local t = {} ---@type string[]
   for p, h in pairs(trust) do
     t[#t + 1] = string.format('%s %s\n', h, p)
   end
@@ -61,7 +61,7 @@ function M.read(path)
     return nil
   end
 
-  local contents
+  local contents ---@type string?
   do
     local f = io.open(fullpath, 'r')
     if not f then
@@ -108,6 +108,11 @@ function M.read(path)
   return contents
 end
 
+---@class vim.trust.opts
+---@field action string
+---@field path? string
+---@field bufnr? integer
+
 --- Manage the trust database.
 ---
 --- The trust database is located at |$XDG_STATE_HOME|/nvim/trust.
@@ -134,6 +139,7 @@ function M.trust(opts)
     },
   })
 
+  ---@cast opts vim.trust.opts
   local path = opts.path
   local bufnr = opts.bufnr
   local action = opts.action
@@ -144,7 +150,7 @@ function M.trust(opts)
     assert(not path, '"path" is not valid when action is "allow"')
   end
 
-  local fullpath
+  local fullpath ---@type string?
   if path then
     fullpath = vim.uv.fs_realpath(vim.fs.normalize(path))
   elseif bufnr then
@@ -165,7 +171,8 @@ function M.trust(opts)
 
   if action == 'allow' then
     local newline = vim.bo[bufnr].fileformat == 'unix' and '\n' or '\r\n'
-    local contents = table.concat(vim.api.nvim_buf_get_lines(bufnr, 0, -1, false), newline)
+    local contents =
+      table.concat(vim.api.nvim_buf_get_lines(bufnr --[[@as integer]], 0, -1, false), newline)
     if vim.bo[bufnr].endofline then
       contents = contents .. newline
     end
diff --git a/runtime/lua/vim/treesitter.lua b/runtime/lua/vim/treesitter.lua
index cc8be72670..0e34cbcbcc 100644
--- a/runtime/lua/vim/treesitter.lua
+++ b/runtime/lua/vim/treesitter.lua
@@ -127,6 +127,7 @@ function M.get_parser(bufnr, lang, opts)
       )
     end
   elseif parsers[bufnr] == nil or parsers[bufnr]:lang() ~= lang then
+    assert(lang, 'lang should be valid')
     parsers[bufnr] = M._create_parser(bufnr, lang, opts)
   end
 
@@ -162,7 +163,7 @@ function M.is_ancestor(dest, source)
     return false
   end
 
-  local current = source
+  local current = source ---@type TSNode?
   while current ~= nil do
     if current == dest then
       return true
@@ -491,7 +492,7 @@ end
 ---                        function, it accepts the buffer number of the source buffer as its only
 ---                        argument and should return a string.
 function M.inspect_tree(opts)
-  ---@cast opts InspectTreeOpts
+  ---@diagnostic disable-next-line: invisible
   require('vim.treesitter.dev').inspect_tree(opts)
 end
 
diff --git a/runtime/lua/vim/treesitter/dev.lua b/runtime/lua/vim/treesitter/dev.lua
index 61d84017d4..db30d638af 100644
--- a/runtime/lua/vim/treesitter/dev.lua
+++ b/runtime/lua/vim/treesitter/dev.lua
@@ -258,7 +258,7 @@ end
 
 --- @private
 ---
---- @param opts InspectTreeOpts
+--- @param opts InspectTreeOpts?
 function M.inspect_tree(opts)
   vim.validate({
     opts = { opts, 't', true },
diff --git a/runtime/lua/vim/uri.lua b/runtime/lua/vim/uri.lua
index 9dce80b77e..2dc817c5c1 100644
--- a/runtime/lua/vim/uri.lua
+++ b/runtime/lua/vim/uri.lua
@@ -60,7 +60,7 @@ end
 ---@param path string Path to file
 ---@return string URI
 function M.uri_from_fname(path)
-  local volume_path, fname = path:match('^([a-zA-Z]:)(.*)')
+  local volume_path, fname = path:match('^([a-zA-Z]:)(.*)') ---@type string?
   local is_windows = volume_path ~= nil
   if is_windows then
     path = volume_path .. M.uri_encode(fname:gsub('\\', '/'))
@@ -82,7 +82,7 @@ function M.uri_from_bufnr(bufnr)
   local fname = vim.api.nvim_buf_get_name(bufnr)
   local volume_path = fname:match('^([a-zA-Z]:).*')
   local is_windows = volume_path ~= nil
-  local scheme
+  local scheme ---@type string?
   if is_windows then
     fname = fname:gsub('\\', '/')
     scheme = fname:match(WINDOWS_URI_SCHEME_PATTERN)
@@ -107,10 +107,9 @@ function M.uri_to_fname(uri)
   uri = M.uri_decode(uri)
   --TODO improve this.
   if is_windows_file_uri(uri) then
-    uri = uri:gsub('^file:/+', '')
-    uri = uri:gsub('/', '\\')
+    uri = uri:gsub('^file:/+', ''):gsub('/', '\\')
   else
-    uri = uri:gsub('^file:/+', '/')
+    uri = uri:gsub('^file:/+', '/') ---@type string
   end
   return uri
 end