refactor(lua): improve type annotations

20 files changed, 64 insertions, 369 deletions

diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index 68dc9d6549..05af2eddc3 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -363,7 +363,6 @@ Lua module: vim.diagnostic                                    *diagnostic-api*
       • {message}     (`string`) The diagnostic text
       • {source}?     (`string`) The source of the diagnostic
       • {code}?       (`string|integer`) The diagnostic code
-      • {_tags}?      (`{ deprecated: boolean, unnecessary: boolean}`)
       • {user_data}?  (`any`) arbitrary data plugins can add
       • {namespace}?  (`integer`)
 
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index e2fcac1bda..72babb067e 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -981,6 +981,9 @@ vim.str_byteindex({str}, {index}, {use_utf16})           *vim.str_byteindex()*
       • {index}      (`integer`)
       • {use_utf16}  (`boolean?`)
 
+    Return: ~
+        (`integer`)
+
 vim.str_utf_end({str}, {index})                            *vim.str_utf_end()*
     Gets the distance (in bytes) from the last byte of the codepoint
     (character) that {index} points to.
diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua
index 75737bd040..3aca3cdfa5 100644
--- a/runtime/lua/vim/_meta/builtin.lua
+++ b/runtime/lua/vim/_meta/builtin.lua
@@ -121,6 +121,7 @@ function vim.stricmp(a, b) end
 --- @param str string
 --- @param index integer
 --- @param use_utf16? boolean
+--- @return integer
 function vim.str_byteindex(str, index, use_utf16) end
 
 --- Gets a list of the starting byte positions of each UTF-8 codepoint in the given string.
diff --git a/runtime/lua/vim/_meta/builtin_types.lua b/runtime/lua/vim/_meta/builtin_types.lua
index 53dd8d95e9..9afb8c84f4 100644
--- a/runtime/lua/vim/_meta/builtin_types.lua
+++ b/runtime/lua/vim/_meta/builtin_types.lua
@@ -34,6 +34,11 @@
 --- @field filename? string
 --- @field lnum integer
 
+--- @class vim.fn.getmarklist.ret.item
+--- @field mark string
+--- @field pos [integer, integer, integer, integer]
+--- @field file string
+
 --- @class vim.fn.getmousepos.ret
 --- @field screenrow integer
 --- @field screencol integer
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index a1600e1cb5..e38c475d09 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -3249,8 +3249,8 @@ function vim.fn.getloclist(nr, what) end
 --- Refer to |getpos()| for getting information about a specific
 --- mark.
 ---
---- @param buf? any
---- @return any
+--- @param buf? integer?
+--- @return vim.fn.getmarklist.ret.item[]
 function vim.fn.getmarklist(buf) end
 
 --- Returns a |List| with all matches previously defined for the
diff --git a/runtime/lua/vim/lsp/_dynamic.lua b/runtime/lua/vim/lsp/_dynamic.lua
index 819b03a63a..27113c0e74 100644
--- a/runtime/lua/vim/lsp/_dynamic.lua
+++ b/runtime/lua/vim/lsp/_dynamic.lua
@@ -24,7 +24,6 @@ function M:supports_registration(method)
 end
 
 --- @param registrations lsp.Registration[]
---- @package
 function M:register(registrations)
   -- remove duplicates
   self:unregister(registrations)
@@ -38,7 +37,6 @@ function M:register(registrations)
 end
 
 --- @param unregisterations lsp.Unregistration[]
---- @package
 function M:unregister(unregisterations)
   for _, unreg in ipairs(unregisterations) do
     local method = unreg.method
@@ -58,7 +56,6 @@ end
 --- @param method string
 --- @param opts? {bufnr: integer?}
 --- @return lsp.Registration? (table|nil) the registration if found
---- @package
 function M:get(method, opts)
   opts = opts or {}
   opts.bufnr = opts.bufnr or vim.api.nvim_get_current_buf()
@@ -78,7 +75,6 @@ end
 
 --- @param method string
 --- @param opts? {bufnr: integer?}
---- @package
 function M:supports(method, opts)
   return self:get(method, opts) ~= nil
 end
diff --git a/runtime/lua/vim/lsp/client.lua b/runtime/lua/vim/lsp/client.lua
index 327cd19125..d3ff918792 100644
--- a/runtime/lua/vim/lsp/client.lua
+++ b/runtime/lua/vim/lsp/client.lua
@@ -436,7 +436,7 @@ local function ensure_list(x)
   return { x }
 end
 
---- @package
+--- @nodoc
 --- @param config vim.lsp.ClientConfig
 --- @return vim.lsp.Client?
 function Client.create(config)
@@ -535,7 +535,7 @@ function Client:_run_callbacks(cbs, error_id, ...)
   end
 end
 
---- @package
+--- @nodoc
 function Client:initialize()
   local config = self.config
 
@@ -656,7 +656,7 @@ end
 --- @param method string LSP method name.
 --- @param params? table LSP request params.
 --- @param handler? lsp.Handler Response |lsp-handler| for this method.
---- @param bufnr? integer Buffer handle (0 for current).
+--- @param bufnr integer Buffer handle (0 for current).
 --- @return boolean status, integer? 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
@@ -861,7 +861,6 @@ function Client:_is_stopped()
   return self.rpc.is_closing()
 end
 
---- @package
 --- Execute a lsp command, either via client command function (if available)
 --- or via workspace/executeCommand (if supported by the server)
 ---
@@ -906,7 +905,6 @@ function Client:_exec_cmd(command, context, handler, on_unsupported)
   self.request(ms.workspace_executeCommand, params, handler, context.bufnr)
 end
 
---- @package
 --- Default handler for the 'textDocument/didOpen' LSP notification.
 ---
 --- @param bufnr integer Number of the buffer, or 0 for current
@@ -942,7 +940,6 @@ function Client:_text_document_did_open_handler(bufnr)
   end)
 end
 
---- @package
 --- Runs the on_attach function from the client's config if it was defined.
 --- @param bufnr integer Buffer number
 function Client:_on_attach(bufnr)
@@ -1065,7 +1062,6 @@ function Client:_on_exit(code, signal)
   )
 end
 
---- @package
 --- Add a directory to the workspace folders.
 --- @param dir string?
 function Client:_add_workspace_folder(dir)
@@ -1088,7 +1084,6 @@ function Client:_add_workspace_folder(dir)
   vim.list_extend(self.workspace_folders, wf)
 end
 
---- @package
 --- Remove a directory to the workspace folders.
 --- @param dir string?
 function Client:_remove_workspace_folder(dir)
diff --git a/runtime/lua/vim/lsp/handlers.lua b/runtime/lua/vim/lsp/handlers.lua
index 38c43893eb..44548fec92 100644
--- a/runtime/lua/vim/lsp/handlers.lua
+++ b/runtime/lua/vim/lsp/handlers.lua
@@ -646,6 +646,7 @@ M[ms.window_showMessage] = function(_, result, ctx, _)
   if message_type == protocol.MessageType.Error then
     err_message('LSP[', client_name, '] ', message)
   else
+    --- @type string
     local message_type_name = protocol.MessageType[message_type]
     api.nvim_out_write(string.format('LSP[%s][%s] %s\n', client_name, message_type_name, message))
   end
diff --git a/runtime/lua/vim/lsp/log.lua b/runtime/lua/vim/lsp/log.lua
index 9f2bd71158..0438ca84af 100644
--- a/runtime/lua/vim/lsp/log.lua
+++ b/runtime/lua/vim/lsp/log.lua
@@ -9,7 +9,7 @@ local log_levels = vim.log.levels
 --- Can be used to lookup the number from the name or the name from the number.
 --- Levels by name: "TRACE", "DEBUG", "INFO", "WARN", "ERROR", "OFF"
 --- Level numbers begin with "TRACE" at 0
---- @type table<string|integer, string|integer>
+--- @type table<string,integer> | table<integer, string>
 --- @nodoc
 log.levels = vim.deepcopy(log_levels)
 
diff --git a/runtime/lua/vim/lsp/protocol.lua b/runtime/lua/vim/lsp/protocol.lua
index 8ac4cc794b..eb18043843 100644
--- a/runtime/lua/vim/lsp/protocol.lua
+++ b/runtime/lua/vim/lsp/protocol.lua
@@ -12,9 +12,6 @@ end
 
 local sysname = vim.uv.os_uname().sysname
 
--- Protocol for the Microsoft Language Server Protocol (mslsp)
-local protocol = {}
-
 local constants = {
   --- @enum lsp.DiagnosticSeverity
   DiagnosticSeverity = {
@@ -46,6 +43,8 @@ local constants = {
     Info = 3,
     -- A log message.
     Log = 4,
+    -- A debug message.
+    Debug = 5,
   },
 
   -- The file event type.
@@ -308,326 +307,18 @@ local constants = {
   },
 }
 
-for k1, v1 in pairs(constants) do
-  local tbl = vim.deepcopy(v1, true)
-  for _, k2 in ipairs(vim.tbl_keys(tbl)) do
-    local v2 = tbl[k2]
-    tbl[v2] = k2
+-- Protocol for the Microsoft Language Server Protocol (mslsp)
+local protocol = {}
+
+--- @diagnostic disable:no-unknown
+for k1, v1 in pairs(vim.deepcopy(constants, true)) do
+  for _, k2 in ipairs(vim.tbl_keys(v1)) do
+    local v2 = v1[k2]
+    v1[v2] = k2
   end
-  protocol[k1] = tbl
+  protocol[k1] = v1
 end
-
---[=[
---Text document specific client capabilities.
-export interface TextDocumentClientCapabilities {
-  synchronization?: {
-    --Whether text document synchronization supports dynamic registration.
-    dynamicRegistration?: boolean;
-    --The client supports sending will save notifications.
-    willSave?: boolean;
-    --The client supports sending a will save request and
-    --waits for a response providing text edits which will
-    --be applied to the document before it is saved.
-    willSaveWaitUntil?: boolean;
-    --The client supports did save notifications.
-    didSave?: boolean;
-  }
-  --Capabilities specific to the `textDocument/completion`
-  completion?: {
-    --Whether completion supports dynamic registration.
-    dynamicRegistration?: boolean;
-    --The client supports the following `CompletionItem` specific
-    --capabilities.
-    completionItem?: {
-      --The client supports snippets as insert text.
-      --
-      --A snippet can define tab stops and placeholders with `$1`, `$2`
-      --and `${3:foo}`. `$0` defines the final tab stop, it defaults to
-      --the end of the snippet. Placeholders with equal identifiers are linked,
-      --that is typing in one will update others too.
-      snippetSupport?: boolean;
-      --The client supports commit characters on a completion item.
-      commitCharactersSupport?: boolean
-      --The client supports the following content formats for the documentation
-      --property. The order describes the preferred format of the client.
-      documentationFormat?: MarkupKind[];
-      --The client supports the deprecated property on a completion item.
-      deprecatedSupport?: boolean;
-      --The client supports the preselect property on a completion item.
-      preselectSupport?: boolean;
-    }
-    completionItemKind?: {
-      --The completion item kind values the client supports. When this
-      --property exists the client also guarantees that it will
-      --handle values outside its set gracefully and falls back
-      --to a default value when unknown.
-      --
-      --If this property is not present the client only supports
-      --the completion items kinds from `Text` to `Reference` as defined in
-      --the initial version of the protocol.
-      valueSet?: CompletionItemKind[];
-    },
-    --The client supports to send additional context information for a
-    --`textDocument/completion` request.
-    contextSupport?: boolean;
-  };
-  --Capabilities specific to the `textDocument/hover`
-  hover?: {
-    --Whether hover supports dynamic registration.
-    dynamicRegistration?: boolean;
-    --The client supports the follow content formats for the content
-    --property. The order describes the preferred format of the client.
-    contentFormat?: MarkupKind[];
-  };
-  --Capabilities specific to the `textDocument/signatureHelp`
-  signatureHelp?: {
-    --Whether signature help supports dynamic registration.
-    dynamicRegistration?: boolean;
-    --The client supports the following `SignatureInformation`
-    --specific properties.
-    signatureInformation?: {
-      --The client supports the follow content formats for the documentation
-      --property. The order describes the preferred format of the client.
-      documentationFormat?: MarkupKind[];
-      --Client capabilities specific to parameter information.
-      parameterInformation?: {
-        --The client supports processing label offsets instead of a
-        --simple label string.
-        --
-        --Since 3.14.0
-        labelOffsetSupport?: boolean;
-      }
-    };
-  };
-  --Capabilities specific to the `textDocument/references`
-  references?: {
-    --Whether references supports dynamic registration.
-    dynamicRegistration?: boolean;
-  };
-  --Capabilities specific to the `textDocument/documentHighlight`
-  documentHighlight?: {
-    --Whether document highlight supports dynamic registration.
-    dynamicRegistration?: boolean;
-  };
-  --Capabilities specific to the `textDocument/documentSymbol`
-  documentSymbol?: {
-    --Whether document symbol supports dynamic registration.
-    dynamicRegistration?: boolean;
-    --Specific capabilities for the `SymbolKind`.
-    symbolKind?: {
-      --The symbol kind values the client supports. When this
-      --property exists the client also guarantees that it will
-      --handle values outside its set gracefully and falls back
-      --to a default value when unknown.
-      --
-      --If this property is not present the client only supports
-      --the symbol kinds from `File` to `Array` as defined in
-      --the initial version of the protocol.
-      valueSet?: SymbolKind[];
-    }
-    --The client supports hierarchical document symbols.
-    hierarchicalDocumentSymbolSupport?: boolean;
-  };
-  --Capabilities specific to the `textDocument/formatting`
-  formatting?: {
-    --Whether formatting supports dynamic registration.
-    dynamicRegistration?: boolean;
-  };
-  --Capabilities specific to the `textDocument/rangeFormatting`
-  rangeFormatting?: {
-    --Whether range formatting supports dynamic registration.
-    dynamicRegistration?: boolean;
-  };
-  --Capabilities specific to the `textDocument/onTypeFormatting`
-  onTypeFormatting?: {
-    --Whether on type formatting supports dynamic registration.
-    dynamicRegistration?: boolean;
-  };
-  --Capabilities specific to the `textDocument/declaration`
-  declaration?: {
-    --Whether declaration supports dynamic registration. If this is set to `true`
-    --the client supports the new `(TextDocumentRegistrationOptions & StaticRegistrationOptions)`
-    --return value for the corresponding server capability as well.
-    dynamicRegistration?: boolean;
-    --The client supports additional metadata in the form of declaration links.
-    --
-    --Since 3.14.0
-    linkSupport?: boolean;
-  };
-  --Capabilities specific to the `textDocument/definition`.
-  --
-  --Since 3.14.0
-  definition?: {
-    --Whether definition supports dynamic registration.
-    dynamicRegistration?: boolean;
-    --The client supports additional metadata in the form of definition links.
-    linkSupport?: boolean;
-  };
-  --Capabilities specific to the `textDocument/typeDefinition`
-  --
-  --Since 3.6.0
-  typeDefinition?: {
-    --Whether typeDefinition supports dynamic registration. If this is set to `true`
-    --the client supports the new `(TextDocumentRegistrationOptions & StaticRegistrationOptions)`
-    --return value for the corresponding server capability as well.
-    dynamicRegistration?: boolean;
-    --The client supports additional metadata in the form of definition links.
-    --
-    --Since 3.14.0
-    linkSupport?: boolean;
-  };
-  --Capabilities specific to the `textDocument/implementation`.
-  --
-  --Since 3.6.0
-  implementation?: {
-    --Whether implementation supports dynamic registration. If this is set to `true`
-    --the client supports the new `(TextDocumentRegistrationOptions & StaticRegistrationOptions)`
-    --return value for the corresponding server capability as well.
-    dynamicRegistration?: boolean;
-    --The client supports additional metadata in the form of definition links.
-    --
-    --Since 3.14.0
-    linkSupport?: boolean;
-  };
-  --Capabilities specific to the `textDocument/codeAction`
-  codeAction?: {
-    --Whether code action supports dynamic registration.
-    dynamicRegistration?: boolean;
-    --The client support code action literals as a valid
-    --response of the `textDocument/codeAction` request.
-    --
-    --Since 3.8.0
-    codeActionLiteralSupport?: {
-      --The code action kind is support with the following value
-      --set.
-      codeActionKind: {
-        --The code action kind values the client supports. When this
-        --property exists the client also guarantees that it will
-        --handle values outside its set gracefully and falls back
-        --to a default value when unknown.
-        valueSet: CodeActionKind[];
-      };
-    };
-  };
-  --Capabilities specific to the `textDocument/codeLens`
-  codeLens?: {
-    --Whether code lens supports dynamic registration.
-    dynamicRegistration?: boolean;
-  };
-  --Capabilities specific to the `textDocument/documentLink`
-  documentLink?: {
-    --Whether document link supports dynamic registration.
-    dynamicRegistration?: boolean;
-  };
-  --Capabilities specific to the `textDocument/documentColor` and the
-  --`textDocument/colorPresentation` request.
-  --
-  --Since 3.6.0
-  colorProvider?: {
-    --Whether colorProvider supports dynamic registration. If this is set to `true`
-    --the client supports the new `(ColorProviderOptions & TextDocumentRegistrationOptions & StaticRegistrationOptions)`
-    --return value for the corresponding server capability as well.
-    dynamicRegistration?: boolean;
-  }
-  --Capabilities specific to the `textDocument/rename`
-  rename?: {
-    --Whether rename supports dynamic registration.
-    dynamicRegistration?: boolean;
-    --The client supports testing for validity of rename operations
-    --before execution.
-    prepareSupport?: boolean;
-  };
-  --Capabilities specific to `textDocument/publishDiagnostics`.
-  publishDiagnostics?: {
-    --Whether the clients accepts diagnostics with related information.
-    relatedInformation?: boolean;
-    --Client supports the tag property to provide meta data about a diagnostic.
-	  --Clients supporting tags have to handle unknown tags gracefully.
-    --Since 3.15.0
-    tagSupport?: {
-      --The tags supported by this client
-      valueSet: DiagnosticTag[];
-    };
-  };
-  --Capabilities specific to `textDocument/foldingRange` requests.
-  --
-  --Since 3.10.0
-  foldingRange?: {
-    --Whether implementation supports dynamic registration for folding range providers. If this is set to `true`
-    --the client supports the new `(FoldingRangeProviderOptions & TextDocumentRegistrationOptions & StaticRegistrationOptions)`
-    --return value for the corresponding server capability as well.
-    dynamicRegistration?: boolean;
-    --The maximum number of folding ranges that the client prefers to receive per document. The value serves as a
-    --hint, servers are free to follow the limit.
-    rangeLimit?: number;
-    --If set, the client signals that it only supports folding complete lines. If set, client will
-    --ignore specified `startCharacter` and `endCharacter` properties in a FoldingRange.
-    lineFoldingOnly?: boolean;
-  };
-}
---]=]
-
---[=[
---Workspace specific client capabilities.
-export interface WorkspaceClientCapabilities {
-  --The client supports applying batch edits to the workspace by supporting
-  --the request 'workspace/applyEdit'
-  applyEdit?: boolean;
-  --Capabilities specific to `WorkspaceEdit`s
-  workspaceEdit?: {
-    --The client supports versioned document changes in `WorkspaceEdit`s
-    documentChanges?: boolean;
-    --The resource operations the client supports. Clients should at least
-    --support 'create', 'rename' and 'delete' files and folders.
-    resourceOperations?: ResourceOperationKind[];
-    --The failure handling strategy of a client if applying the workspace edit
-    --fails.
-    failureHandling?: FailureHandlingKind;
-  };
-  --Capabilities specific to the `workspace/didChangeConfiguration` notification.
-  didChangeConfiguration?: {
-    --Did change configuration notification supports dynamic registration.
-    dynamicRegistration?: boolean;
-  };
-  --Capabilities specific to the `workspace/didChangeWatchedFiles` notification.
-  didChangeWatchedFiles?: {
-    --Did change watched files notification supports dynamic registration. Please note
-    --that the current protocol doesn't support static configuration for file changes
-    --from the server side.
-    dynamicRegistration?: boolean;
-  };
-  --Capabilities specific to the `workspace/symbol` request.
-  symbol?: {
-    --Symbol request supports dynamic registration.
-    dynamicRegistration?: boolean;
-    --Specific capabilities for the `SymbolKind` in the `workspace/symbol` request.
-    symbolKind?: {
-      --The symbol kind values the client supports. When this
-      --property exists the client also guarantees that it will
-      --handle values outside its set gracefully and falls back
-      --to a default value when unknown.
-      --
-      --If this property is not present the client only supports
-      --the symbol kinds from `File` to `Array` as defined in
-      --the initial version of the protocol.
-      valueSet?: SymbolKind[];
-    }
-  };
-  --Capabilities specific to the `workspace/executeCommand` request.
-  executeCommand?: {
-    --Execute command supports dynamic registration.
-    dynamicRegistration?: boolean;
-  };
-  --The client has support for workspace folders.
-  --
-  --Since 3.6.0
-  workspaceFolders?: boolean;
-  --The client supports `workspace/configuration` requests.
-  --
-  --Since 3.6.0
-  configuration?: boolean;
-}
---]=]
+--- @diagnostic enable:no-unknown
 
 --- Gets a new ClientCapabilities object describing the LSP client
 --- capabilities.
@@ -1250,14 +941,5 @@ protocol.Methods = {
   --- The `workspace/workspaceFolders` is sent from the server to the client to fetch the open workspace folders.
   workspace_workspaceFolders = 'workspace/workspaceFolders',
 }
-local function freeze(t)
-  return setmetatable({}, {
-    __index = t,
-    __newindex = function()
-      error('cannot modify immutable table')
-    end,
-  })
-end
-protocol.Methods = freeze(protocol.Methods)
 
 return protocol
diff --git a/runtime/lua/vim/lsp/rpc.lua b/runtime/lua/vim/lsp/rpc.lua
index 3c63a12da2..5e2b041a0a 100644
--- a/runtime/lua/vim/lsp/rpc.lua
+++ b/runtime/lua/vim/lsp/rpc.lua
@@ -140,7 +140,7 @@ local client_errors = {
   SERVER_RESULT_CALLBACK_ERROR = 7,
 }
 
---- @type table<string|integer, string|integer>
+--- @type table<string,integer> | table<integer,string>
 --- @nodoc
 M.client_errors = vim.deepcopy(client_errors)
 for k, v in pairs(client_errors) do
@@ -502,7 +502,7 @@ function Client:handle_body(body)
       if decoded.error then
         decoded.error = setmetatable(decoded.error, {
           __tostring = M.format_rpc_error,
-        }) --- @type table
+        })
       end
       self:try_call(
         M.client_errors.SERVER_RESULT_CALLBACK_ERROR,
diff --git a/runtime/lua/vim/lsp/semantic_tokens.lua b/runtime/lua/vim/lsp/semantic_tokens.lua
index 279956658c..f92c0eb2e6 100644
--- a/runtime/lua/vim/lsp/semantic_tokens.lua
+++ b/runtime/lua/vim/lsp/semantic_tokens.lua
@@ -773,7 +773,6 @@ function M.highlight_token(token, bufnr, client_id, hl_group, opts)
   })
 end
 
---- @package
 --- |lsp-handler| for the method `workspace/semanticTokens/refresh`
 ---
 --- Refresh requests are sent by the server to indicate a project-wide change
diff --git a/runtime/lua/vim/lsp/util.lua b/runtime/lua/vim/lsp/util.lua
index 088d57b6d6..ae6de591b3 100644
--- a/runtime/lua/vim/lsp/util.lua
+++ b/runtime/lua/vim/lsp/util.lua
@@ -238,6 +238,7 @@ end
 ---@param rows integer[] zero-indexed line numbers
 ---@return table<integer, string>|string a table mapping rows to lines
 local function get_lines(bufnr, rows)
+  --- @type integer[]
   rows = type(rows) == 'table' and rows or { rows }
 
   -- This is needed for bufload and bufloaded
@@ -246,7 +247,7 @@ local function get_lines(bufnr, rows)
   end
 
   local function buf_lines()
-    local lines = {}
+    local lines = {} --- @type table<integer,string>
     for _, row in ipairs(rows) do
       lines[row] = (api.nvim_buf_get_lines(bufnr, row, row + 1, false) or { '' })[1]
     end
@@ -274,11 +275,11 @@ local function get_lines(bufnr, rows)
   if not fd then
     return ''
   end
-  local stat = uv.fs_fstat(fd)
-  local data = uv.fs_read(fd, stat.size, 0)
+  local stat = assert(uv.fs_fstat(fd))
+  local data = assert(uv.fs_read(fd, stat.size, 0))
   uv.fs_close(fd)
 
-  local lines = {} -- rows we need to retrieve
+  local lines = {} --- @type table<integer,true|string> rows we need to retrieve
   local need = 0 -- keep track of how many unique rows we need
   for _, row in pairs(rows) do
     if not lines[row] then
@@ -307,7 +308,7 @@ local function get_lines(bufnr, rows)
       lines[i] = ''
     end
   end
-  return lines
+  return lines --[[@as table<integer,string>]]
 end
 
 --- Gets the zero-indexed line from the given buffer.
@@ -322,7 +323,8 @@ local function get_line(bufnr, row)
 end
 
 --- Position is a https://microsoft.github.io/language-server-protocol/specifications/specification-current/#position
----@param offset_encoding string|nil utf-8|utf-16|utf-32
+---@param position lsp.Position
+---@param offset_encoding? string utf-8|utf-16|utf-32
 ---@return integer
 local function get_line_byte_from_position(bufnr, position, offset_encoding)
   -- LSP's line and characters are 0-indexed
@@ -366,6 +368,7 @@ function M.apply_text_edits(text_edits, bufnr, offset_encoding)
 
   -- Fix reversed range and indexing each text_edits
   local index = 0
+  --- @param text_edit lsp.TextEdit
   text_edits = vim.tbl_map(function(text_edit)
     index = index + 1
     text_edit._index = index
@@ -383,6 +386,9 @@ function M.apply_text_edits(text_edits, bufnr, offset_encoding)
   end, text_edits)
 
   -- Sort text_edits
+  ---@param a lsp.TextEdit | { _index: integer }
+  ---@param b lsp.TextEdit | { _index: integer }
+  ---@return boolean
   table.sort(text_edits, function(a, b)
     if a.range.start.line ~= b.range.start.line then
       return a.range.start.line > b.range.start.line
@@ -393,10 +399,11 @@ function M.apply_text_edits(text_edits, bufnr, offset_encoding)
     if a._index ~= b._index then
       return a._index < b._index
     end
+    return false
   end)
 
   -- save and restore local marks since they get deleted by nvim_buf_set_lines
-  local marks = {}
+  local marks = {} --- @type table<string,[integer,integer]>
   for _, m in pairs(vim.fn.getmarklist(bufnr)) do
     if m.mark:match("^'[a-z]$") then
       marks[m.mark:sub(2, 2)] = { m.pos[2], m.pos[3] - 1 } -- api-indexed
diff --git a/runtime/lua/vim/treesitter/_fold.lua b/runtime/lua/vim/treesitter/_fold.lua
index eecf1ad6b1..04a3c62cf1 100644
--- a/runtime/lua/vim/treesitter/_fold.lua
+++ b/runtime/lua/vim/treesitter/_fold.lua
@@ -383,7 +383,6 @@ local function on_bytes(bufnr, foldinfo, start_row, start_col, old_row, old_col,
   end
 end
 
----@package
 ---@param lnum integer|nil
 ---@return string
 function M.foldexpr(lnum)
diff --git a/runtime/lua/vim/treesitter/_meta.lua b/runtime/lua/vim/treesitter/_meta.lua
index 177699a207..2aedf5754e 100644
--- a/runtime/lua/vim/treesitter/_meta.lua
+++ b/runtime/lua/vim/treesitter/_meta.lua
@@ -33,6 +33,7 @@ error('Cannot require a meta file')
 ---@field iter_children fun(self: TSNode): fun(): TSNode, string
 ---@field field fun(self: TSNode, name: string): TSNode[]
 ---@field byte_length fun(self: TSNode): integer
+---@field __has_ancestor fun(self: TSNode, node_types: string[]): boolean
 local TSNode = {}
 
 ---@alias TSLoggerCallback fun(logtype: 'parse'|'lex', msg: string)
@@ -62,6 +63,7 @@ local TSNode = {}
 ---@field patterns table<integer, (integer|string)[][]>
 
 --- @param lang string
+--- @return table
 vim._ts_inspect_language = function(lang) end
 
 ---@return integer
diff --git a/runtime/lua/vim/treesitter/highlighter.lua b/runtime/lua/vim/treesitter/highlighter.lua
index d2f986b874..003f7e0169 100644
--- a/runtime/lua/vim/treesitter/highlighter.lua
+++ b/runtime/lua/vim/treesitter/highlighter.lua
@@ -47,7 +47,7 @@ function TSHighlighterQuery:get_hl_from_capture(capture)
   return self.hl_cache[capture]
 end
 
----@package
+---@nodoc
 function TSHighlighterQuery:query()
   return self._query
 end
@@ -75,7 +75,7 @@ local TSHighlighter = {
 
 TSHighlighter.__index = TSHighlighter
 
----@package
+---@nodoc
 ---
 --- Creates a highlighter for `tree`.
 ---
@@ -232,7 +232,7 @@ function TSHighlighter:on_changedtree(changes)
 end
 
 --- Gets the query used for @param lang
----@package
+---@nodoc
 ---@param lang string Language used by the highlighter.
 ---@return vim.treesitter.highlighter.Query
 function TSHighlighter:get_query(lang)
diff --git a/runtime/lua/vim/treesitter/languagetree.lua b/runtime/lua/vim/treesitter/languagetree.lua
index b0812123b9..3523ea95e0 100644
--- a/runtime/lua/vim/treesitter/languagetree.lua
+++ b/runtime/lua/vim/treesitter/languagetree.lua
@@ -98,9 +98,9 @@ local LanguageTree = {}
 
 LanguageTree.__index = LanguageTree
 
---- @package
+--- @nodoc
 ---
---- |LanguageTree| contains a tree of parsers: the root treesitter parser for {lang} and any
+--- LanguageTree contains a tree of parsers: the root treesitter parser for {lang} and any
 --- "injected" language parsers, which themselves may inject other languages, recursively.
 ---
 ---@param source (integer|string) Buffer or text string to parse
@@ -951,7 +951,7 @@ function LanguageTree:_edit(
   end
 end
 
----@package
+---@nodoc
 ---@param bufnr integer
 ---@param changed_tick integer
 ---@param start_row integer
@@ -1023,12 +1023,12 @@ function LanguageTree:_on_bytes(
   )
 end
 
----@package
+---@nodoc
 function LanguageTree:_on_reload()
   self:invalidate(true)
 end
 
----@package
+---@nodoc
 function LanguageTree:_on_detach(...)
   self:invalidate(true)
   self:_do_callback('detach', ...)
diff --git a/scripts/gen_vimdoc.lua b/scripts/gen_vimdoc.lua
index 507426c8c0..dc384c12f5 100755
--- a/scripts/gen_vimdoc.lua
+++ b/scripts/gen_vimdoc.lua
@@ -421,8 +421,11 @@ local function render_type(ty, generics, default)
 end
 
 --- @param p nvim.luacats.parser.param|nvim.luacats.parser.field
-local function should_render_param(p)
-  return not p.access and not contains(p.name, { '_', 'self' })
+local function should_render_field_or_param(p)
+  return not p.nodoc
+    and not p.access
+    and not contains(p.name, { '_', 'self' })
+    and not vim.startswith(p.name, '_')
 end
 
 --- @param desc? string
@@ -524,7 +527,7 @@ end
 local function render_fields_or_params(xs, generics, classes, exclude_types)
   local ret = {} --- @type string[]
 
-  xs = vim.tbl_filter(should_render_param, xs)
+  xs = vim.tbl_filter(should_render_field_or_param, xs)
 
   local indent = 0
   for _, p in ipairs(xs) do
diff --git a/scripts/luacats_parser.lua b/scripts/luacats_parser.lua
index 66fe8ed616..e73a42111d 100644
--- a/scripts/luacats_parser.lua
+++ b/scripts/luacats_parser.lua
@@ -46,6 +46,7 @@ local luacats_grammar = require('scripts.luacats_grammar')
 --- @field type string
 --- @field desc string
 --- @field access? 'private'|'package'|'protected'
+--- @field nodoc? true
 
 --- @class nvim.luacats.parser.class
 --- @field kind 'class'
@@ -270,6 +271,7 @@ local function fun2field(fun)
     type = table.concat(parts, ''),
     access = fun.access,
     desc = fun.desc,
+    nodoc = fun.nodoc,
   }
 end
 
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index 3c99ba22c2..f303878897 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -4047,8 +4047,9 @@ M.funcs = {
 
     ]=],
     name = 'getmarklist',
-    params = { { 'buf', 'any' } },
+    params = { { 'buf', 'integer?' } },
     signature = 'getmarklist([{buf}])',
+    returns = 'vim.fn.getmarklist.ret.item[]',
   },
   getmatches = {
     args = { 0, 1 },