diff --git a/src/clint.lua b/src/clint.lua
index 1931180798..c4cd2dd753 100755
--- a/src/clint.lua
+++ b/src/clint.lua
@@ -212,7 +212,7 @@ function CppLintState:suppress_errors_from(fname)
     local ok2, data = pcall(vim.json.decode, line)
     if ok2 then
       local fname2, lines, category = data[1], data[2], data[3]
-      local lines_tuple = vim.tbl_islist(lines) and lines or { lines }
+      local lines_tuple = vim.islist(lines) and lines or { lines }
       self.suppressed_errors[fname2][vim.inspect(lines_tuple)][category] = true
     end
   end
diff --git a/src/gen/c_grammar.lua b/src/gen/c_grammar.lua
index 356d5f80cd..48d27d67af 100644
--- a/src/gen/c_grammar.lua
+++ b/src/gen/c_grammar.lua
@@ -50,11 +50,15 @@
 --- @class nvim.c_grammar.Empty
 --- @field [1] 'empty'
 
+--- @class nvim.c_grammar.Comment
+--- @field comment string
+
 --- @alias nvim.c_grammar.result
 --- | nvim.c_grammar.Proto
 --- | nvim.c_grammar.Preproc
 --- | nvim.c_grammar.Empty
 --- | nvim.c_grammar.Keyset
+--- | nvim.c_grammar.Comment
 
 --- @class nvim.c_grammar
 --- @field match fun(self, input: string): nvim.c_grammar.result[]
diff --git a/src/gen/cdoc_parser.lua b/src/gen/cdoc_parser.lua
index beeb2a3a8f..f754d06642 100644
--- a/src/gen/cdoc_parser.lua
+++ b/src/gen/cdoc_parser.lua
@@ -10,7 +10,7 @@ local api_type = require('gen.api_types')
 --- @class nvim.cdoc.parser.return
 --- @field name string
 --- @field type string
---- @field desc string
+--- @field desc? string
 
 --- @class nvim.cdoc.parser.note
 --- @field desc string
@@ -25,7 +25,8 @@ local api_type = require('gen.api_types')
 --- @field returns nvim.cdoc.parser.return[]
 --- @field desc string
 --- @field deprecated? true
---- @field since? string
+--- @field deprecated_since? integer
+--- @field since? string|integer
 --- @field attrs? string[]
 --- @field nodoc? true
 --- @field notes? nvim.cdoc.parser.note[]
@@ -107,6 +108,8 @@ local function process_doc_line(line, state)
     table.insert(cur_obj.params, state.last_doc_item)
   elseif kind == 'return' then
     cur_obj.returns = { {
+      name = '',
+      type = '',
       desc = parsed.desc,
     } }
     state.last_doc_item_indent = nil
@@ -132,7 +135,7 @@ local function process_doc_line(line, state)
   end
 end
 
---- @param item table
+--- @param item nvim.c_grammar.Proto
 --- @param state nvim.cdoc.parser.State
 local function process_proto(item, state)
   state.cur_obj = state.cur_obj or {}
@@ -160,7 +163,11 @@ local function process_proto(item, state)
     end
   end
 
-  cur_obj.returns = cur_obj.returns or { {} }
+  cur_obj.returns = cur_obj.returns or { {
+    name = '',
+    type = '',
+    desc = nil,
+  } }
   cur_obj.returns[1].type = api_type(item.return_type)
 
   for _, a in ipairs({
@@ -191,7 +198,7 @@ end
 local M = {}
 
 --- @param filename string
---- @return {} classes
+--- @return table<string,nvim.luacats.parser.class> classes
 --- @return nvim.cdoc.parser.fun[] funs
 --- @return string[] briefs
 function M.parse(filename)
@@ -208,7 +215,7 @@ function M.parse(filename)
     else
       add_doc_lines_to_obj(state)
       if item[1] == 'proto' then
-        process_proto(item, state)
+        process_proto(item --[[@as nvim.c_grammar.Proto]], state)
         table.insert(funs, state.cur_obj)
       end
       local cur_obj = state.cur_obj
diff --git a/src/gen/gen_api_dispatch.lua b/src/gen/gen_api_dispatch.lua
index fd40d662bb..c8b1de455e 100644
--- a/src/gen/gen_api_dispatch.lua
+++ b/src/gen/gen_api_dispatch.lua
@@ -294,7 +294,6 @@ local metadata_output = assert(io.open(exported_funcs_metadata_outputf, 'wb'))
 metadata_output:write(vim.mpack.encode(exported_functions))
 metadata_output:close()
 
---- @type integer[]
 -- start building the dispatch wrapper output
 local output = assert(io.open(dispatch_outputf, 'wb'))
 
@@ -682,6 +681,8 @@ local mpack_output = assert(io.open(eval_funcs_metadata_outputf, 'wb'))
 mpack_output:write(vim.mpack.encode(functions))
 mpack_output:close()
 
+--- @param output_handle file*
+--- @param headers_to_include string[]
 local function include_headers(output_handle, headers_to_include)
   for i = 1, #headers_to_include do
     if headers_to_include[i]:sub(-12) ~= '.generated.h' then
diff --git a/src/gen/gen_api_metadata.lua b/src/gen/gen_api_metadata.lua
index 59824caffe..45c757da27 100644
--- a/src/gen/gen_api_metadata.lua
+++ b/src/gen/gen_api_metadata.lua
@@ -9,12 +9,12 @@ local nvim_version_inputf = arg[5] -- nvim version
 local dump_bin_array_inputf = arg[6]
 local api_metadata_outputf = arg[7]
 
-local version = loadfile(nvim_version_inputf)()
+local version = loadfile(nvim_version_inputf)() --[[@as {[1]: string, [2]: any}[] ]]
 local git_version = io.open(git_version_inputf):read '*a'
 local version_build = git_version:match('#define NVIM_VERSION_BUILD "([^"]+)"') or vim.NIL
 
-local text = io.open(ui_options_inputf):read '*a'
-local ui_options_text = text:match('ui_ext_names%[][^{]+{([^}]+)}')
+local text = assert(io.open(ui_options_inputf)):read '*a'
+local ui_options_text = assert(text:match('ui_ext_names%[][^{]+{([^}]+)}')) --[[@as string]]
 local ui_options = { 'rgb' }
 for x in ui_options_text:gmatch('"([a-z][a-z_]+)"') do
   table.insert(ui_options, x)
diff --git a/src/gen/gen_api_ui_events.lua b/src/gen/gen_api_ui_events.lua
index e5bbe8c3b3..01b4c260fa 100644
--- a/src/gen/gen_api_ui_events.lua
+++ b/src/gen/gen_api_ui_events.lua
@@ -2,11 +2,11 @@
 local mpack = vim.mpack
 
 assert(#arg == 5)
-local input = io.open(arg[1], 'rb')
-local call_output = io.open(arg[2], 'wb')
-local remote_output = io.open(arg[3], 'wb')
-local metadata_output = io.open(arg[4], 'wb')
-local client_output = io.open(arg[5], 'wb')
+local input = assert(io.open(arg[1], 'rb'))
+local call_output = assert(io.open(arg[2], 'wb'))
+local remote_output = assert(io.open(arg[3], 'wb'))
+local metadata_output = assert(io.open(arg[4], 'wb'))
+local client_output = assert(io.open(arg[5], 'wb'))
 
 local c_grammar = require('gen.c_grammar')
 local events = c_grammar.grammar:match(input:read('*all'))
diff --git a/src/gen/gen_char_blob.lua b/src/gen/gen_char_blob.lua
index 285c9e06ac..230866c35d 100644
--- a/src/gen/gen_char_blob.lua
+++ b/src/gen/gen_char_blob.lua
@@ -25,7 +25,7 @@ end
 assert(#arg >= 3 and (#arg - 1) % 2 == 0)
 
 local target_file = arg[1] or error('Need a target file')
-local target = io.open(target_file, 'w')
+local target = assert(io.open(target_file, 'w'))
 
 target:write('#include <stdint.h>\n\n')
 
diff --git a/src/gen/gen_declarations.lua b/src/gen/gen_declarations.lua
index c0fd0381e8..6ed83846f8 100644
--- a/src/gen/gen_declarations.lua
+++ b/src/gen/gen_declarations.lua
@@ -66,7 +66,6 @@ local function process_decl(d)
   return d .. ';'
 end
 
---- @param fname string
 --- @param text string
 --- @return string[] static
 --- @return string[] non_static
diff --git a/src/gen/gen_eval.lua b/src/gen/gen_eval.lua
index 97887ce676..7ba60e9263 100644
--- a/src/gen/gen_eval.lua
+++ b/src/gen/gen_eval.lua
@@ -90,11 +90,14 @@ hashpipe:write('static const EvalFuncDef functions[] = {\n')
 
 for _, name in ipairs(neworder) do
   local def = funcs[name]
-  local args = def.args or 0
-  if type(args) == 'number' then
-    args = { args, args }
-  elseif #args == 1 then
-    args[2] = 'MAX_FUNC_ARGS'
+  local min_args = 0
+  local max_args = 0 --- @type integer|string
+  local def_args = def.args
+  if type(def_args) == 'number' then
+    min_args, max_args = def_args, def_args
+  elseif type(def_args) == 'table' then
+    min_args = def_args[1] or 0
+    max_args = def_args[2] or 'MAX_FUNC_ARGS'
   end
   local base = def.base or 'BASE_NONE'
   local func = def.func or ('f_' .. name)
@@ -103,8 +106,8 @@ for _, name in ipairs(neworder) do
   hashpipe:write(
     ('  { "%s", %s, %s, %s, %s, &%s, %s },\n'):format(
       name,
-      args[1],
-      args[2],
+      min_args,
+      max_args,
       base,
       fast,
       func,
diff --git a/src/gen/gen_eval_files.lua b/src/gen/gen_eval_files.lua
index f9e721b1ba..928c218e7d 100755
--- a/src/gen/gen_eval_files.lua
+++ b/src/gen/gen_eval_files.lua
@@ -395,7 +395,7 @@ local function render_eval_meta(f, fun, write)
     write('--- @deprecated')
   end
 
-  local desc = fun.desc
+  local desc = fun.desc --[[@as string?]]
 
   if desc then
     --- @type string
@@ -406,7 +406,9 @@ local function render_eval_meta(f, fun, write)
     end
   end
 
-  for _, text in ipairs(vim.fn.reverse(fun.generics or {})) do
+  for _, text in
+    ipairs(vim.fn.reverse(fun.generics or {} --[[@as string[] ]]))
+  do
     write(fmt('--- @generic %s', text))
   end
 
@@ -586,7 +588,12 @@ local function render_option_meta(_f, opt, write)
     write('--- @type ' .. OPTION_TYPES[opt.type])
   end
 
-  write('vim.o.' .. opt.full_name .. ' = ' .. render_option_default(opt.defaults))
+  write(
+    'vim.o.'
+      .. opt.full_name
+      .. ' = '
+      .. render_option_default(opt.defaults --[[@as vim.option_defaults]])
+  )
   if opt.abbreviation then
     write('vim.o.' .. opt.abbreviation .. ' = vim.o.' .. opt.full_name)
   end
@@ -777,7 +784,7 @@ local function render_option_doc(_f, opt, write)
 
   local otype = opt.type == 'boolean' and 'boolean' or opt.type
   if opt.defaults.doc or opt.defaults.if_true ~= nil or opt.defaults.meta ~= nil then
-    local v = render_option_default(opt.defaults, true)
+    local v = render_option_default(opt.defaults --[[@as vim.option_defaults]], true)
     local pad = string.rep('\t', math.max(1, math.ceil((24 - #name_str) / 8)))
     if opt.defaults.doc then
       local deflen = #fmt('%s%s%s (', name_str, pad, otype)
diff --git a/src/gen/gen_events.lua b/src/gen/gen_events.lua
index 76072c59d4..8e93c9cde0 100644
--- a/src/gen/gen_events.lua
+++ b/src/gen/gen_events.lua
@@ -3,7 +3,9 @@ local names_file = arg[2]
 local auevents_file = arg[3]
 
 local hashy = require('gen.hashy')
-local auevents = loadfile(auevents_file)()
+
+---@type {events: table<string, boolean>, aliases: table<string, string>}
+local auevents = assert(loadfile(auevents_file))()
 local events = auevents.events
 local aliases = auevents.aliases
 
diff --git a/src/gen/gen_ex_cmds.lua b/src/gen/gen_ex_cmds.lua
index becb269e4b..67b124bfec 100644
--- a/src/gen/gen_ex_cmds.lua
+++ b/src/gen/gen_ex_cmds.lua
@@ -6,8 +6,8 @@ local enumfname = arg[1] -- '/ex_cmds_enum.generated.h'
 local defsfname = arg[2] -- '/ex_cmds_defs.generated.h'
 local ex_cmds_name = arg[3] -- 'ex_cmds.lua'
 
-local enumfile = io.open(enumfname, 'w')
-local defsfile = io.open(defsfname, 'w')
+local enumfile = assert(io.open(enumfname, 'w'))
+local defsfile = assert(io.open(defsfname, 'w'))
 
 local bit = require 'bit'
 local ex_cmds = loadfile(ex_cmds_name)()
diff --git a/src/gen/gen_filetype.lua b/src/gen/gen_filetype.lua
index 55bed70e6c..c2220fe646 100644
--- a/src/gen/gen_filetype.lua
+++ b/src/gen/gen_filetype.lua
@@ -204,7 +204,7 @@ do
       end
     end
   end
-  local f = io.open(filetype_lua, 'w')
+  local f = assert(io.open(filetype_lua, 'w'))
   f:write(table.concat(lines, '\n') .. '\n')
   f:close()
 end
diff --git a/src/gen/gen_help_html.lua b/src/gen/gen_help_html.lua
index e858a94cb2..ddf2a14f25 100644
--- a/src/gen/gen_help_html.lua
+++ b/src/gen/gen_help_html.lua
@@ -244,6 +244,9 @@ local function is_noise(line, noise_lines)
 end
 
 --- Creates a github issue URL at neovim/tree-sitter-vimdoc with prefilled content.
+--- @param fname string
+--- @param to_fname string
+--- @param sample_text string
 --- @return string
 local function get_bug_url_vimdoc(fname, to_fname, sample_text)
   local this_url = string.format('https://neovim.io/doc/user/%s', vim.fs.basename(to_fname))
@@ -260,6 +263,10 @@ local function get_bug_url_vimdoc(fname, to_fname, sample_text)
 end
 
 --- Creates a github issue URL at neovim/neovim with prefilled content.
+--- @param fname string
+--- @param to_fname string
+--- @param sample_text string
+--- @param token_name? string
 --- @return string
 local function get_bug_url_nvim(fname, to_fname, sample_text, token_name)
   local this_url = string.format('https://neovim.io/doc/user/%s', vim.fs.basename(to_fname))
@@ -481,7 +488,7 @@ local function visit_validate(root, level, lang_tree, opt, stats)
     and (not vim.tbl_contains({ 'codespan', 'taglink', 'tag' }, parent))
   then
     local text_nopunct = vim.fn.trim(text, '.,', 0) -- Ignore some punctuation.
-    local fname_basename = assert(vim.fs.basename(opt.fname))
+    local fname_basename = assert(vim.fs.basename(opt.fname --[[ @as string ]]))
     if spell_dict[text_nopunct] then
       local should_ignore = (
         spell_ignore_files[fname_basename] == true
@@ -791,12 +798,16 @@ local function get_helpfiles(dir, include)
 end
 
 --- Populates the helptags map.
+--- @param help_dir string
+--- @return table<string, string>
 local function _get_helptags(help_dir)
+  ---@type table<string, string>
   local m = {}
   -- Load a random help file to convince taglist() to do its job.
   vim.cmd(string.format('split %s/api.txt', help_dir))
   vim.cmd('lcd %:p:h')
-  for _, item in ipairs(vim.fn.taglist('.*')) do
+  local tags = vim.fn.taglist('.*') --[[ @as {name: string, filename: string}[] ]]
+  for _, item in ipairs(tags) do
     if vim.endswith(item.filename, '.txt') then
       m[item.name] = item.filename
     end
diff --git a/src/gen/gen_helptags.lua b/src/gen/gen_helptags.lua
index 41fb77e128..38ee913b4c 100644
--- a/src/gen/gen_helptags.lua
+++ b/src/gen/gen_helptags.lua
@@ -4,7 +4,7 @@
 local out = arg[1]
 local dir = arg[2]
 
-local dirfd = vim.uv.fs_opendir(dir, nil, 1)
+local dirfd = assert(vim.uv.fs_opendir(dir, nil, 1))
 local files = {}
 while true do
   local file = dirfd:readdir()
@@ -60,8 +60,8 @@ table.sort(tags, function(a, b)
   return a[1] < b[1]
 end)
 
-local f = io.open(out, 'w')
-local lasttagname, lastfn = nil
+local f = assert(io.open(out, 'w'))
+local lasttagname, lastfn = nil, nil
 for _, tag in ipairs(tags) do
   local tagname, fn = unpack(tag)
   if tagname == lasttagname then
diff --git a/src/gen/gen_keycodes.lua b/src/gen/gen_keycodes.lua
index 98b714dffe..c82239e3ed 100644
--- a/src/gen/gen_keycodes.lua
+++ b/src/gen/gen_keycodes.lua
@@ -2,8 +2,9 @@ local names_file = arg[1]
 local keycodes_file = arg[2]
 
 local hashy = require('gen.hashy')
-local keycodes = loadfile(keycodes_file)()
 
+---@type {names: [string, string][]}
+local keycodes = assert(loadfile(keycodes_file))()
 local keycode_names = keycodes.names
 
 local hashorder = {} --- @type string[]
diff --git a/src/gen/gen_terminfo.lua b/src/gen/gen_terminfo.lua
index ce78cfe087..2ecf635ac9 100644
--- a/src/gen/gen_terminfo.lua
+++ b/src/gen/gen_terminfo.lua
@@ -147,6 +147,7 @@ local function quote(str)
   return '"' .. str .. '"'
 end
 
+--- @type fun(...: any)
 local dbg = function() end
 -- dbg = print
 
@@ -199,7 +200,9 @@ for _, entry in ipairs(entries) do
   local boolpat = prepat .. ','
   local numpat = prepat .. '#([^,]+),'
   local strpat = prepat .. '=([^,]+),'
-  local bools, nums, strs = {}, {}, {}
+  local bools = {} --- @type table<string, true>
+  local nums = {} --- @type table<string, string>
+  local strs = {} --- @type table<string, string>
   for i, line in ipairs(lines) do
     local boolmatch = string.match(line, boolpat)
     local nummatch, numval = string.match(line, numpat)
diff --git a/src/gen/gen_vimdoc.lua b/src/gen/gen_vimdoc.lua
index d93fb4d6cd..c0bd22dfaf 100755
--- a/src/gen/gen_vimdoc.lua
+++ b/src/gen/gen_vimdoc.lua
@@ -54,10 +54,15 @@ local INDENTATION = 4
 --- @field helptag_fmt fun(name: string): string|string[]
 ---
 --- Per-function helptag.
---- @field fn_helptag_fmt? fun(fun: nvim.luacats.parser.fun): string
+--- @field fn_helptag_fmt? fun(fun: nvim.gen_vimdoc.HelptagTarget): string
 ---
 --- @field append_only? string[]
 
+---@alias nvim.gen_vimdoc.HelptagTarget
+---| nvim.luacats.parser.fun
+---| nvim.luacats.parser.field
+---| nvim.luacats.parser.param
+
 local function contains(t, xs)
   return vim.tbl_contains(xs, t)
 end
@@ -84,13 +89,13 @@ local function nvim_api_info()
         prerelease = m2 == 'true'
       end
     end
-    nvim_api_info_ = { level = level, prerelease = prerelease }
+    nvim_api_info_ = { level = assert(level), prerelease = assert(prerelease) }
   end
 
   return nvim_api_info_
 end
 
---- @param fun nvim.luacats.parser.fun
+--- @param fun nvim.gen_vimdoc.HelptagTarget
 --- @return string
 local function fn_helptag_fmt_common(fun)
   local fn_sfx = fun.table and '' or '()'
diff --git a/src/gen/luacats_parser.lua b/src/gen/luacats_parser.lua
index 31c02efbda..98185d7498 100644
--- a/src/gen/luacats_parser.lua
+++ b/src/gen/luacats_parser.lua
@@ -461,6 +461,7 @@ end
 --- @param filename string
 --- @param uncommitted nvim.luacats.parser.obj[]
 -- luacheck: no unused
+---@diagnostic disable-next-line: unused-function, unused-local
 local function dump_uncommitted(filename, uncommitted)
   local out_path = 'luacats-uncommited/' .. filename:gsub('/', '%%') .. '.txt'
   if #uncommitted > 0 then