docs: improve/add documentation of Lua types

- Added `@inlinedoc` so single use Lua types can be inlined into the
  functions docs. E.g.

  ```lua
  --- @class myopts
  --- @inlinedoc
  ---
  --- Documentation for some field
  --- @field somefield integer

  --- @param opts myOpts
  function foo(opts)
  end
  ```

  Will be rendered as

  ```
  foo(opts)

    Parameters:
      - {opts} (table) Object with the fields:
               - somefield (integer) Documentation
                 for some field
  ```

- Marked many classes with with `@nodoc` or `(private)`.
  We can eventually introduce these when we want to.

34 files changed, 838 insertions, 750 deletions

diff --git a/runtime/lua/tohtml.lua b/runtime/lua/tohtml.lua
index e3c7fc68c0..52e0742ef3 100644
--- a/runtime/lua/tohtml.lua
+++ b/runtime/lua/tohtml.lua
@@ -25,13 +25,7 @@
 -- Remarks:
 -- - Not all visuals are supported, so it may differ.
 
---- @class vim.tohtml.opt
---- @field title? string|false
---- @field number_lines? boolean
---- @field font? string[]|string
---- @field width? integer
-
---- @class vim.tohtml.state.global
+--- @class (private) vim.tohtml.state.global
 --- @field background string
 --- @field foreground string
 --- @field title string|false
@@ -39,7 +33,7 @@
 --- @field highlights_name table<integer,string>
 --- @field conf vim.tohtml.opt
 
---- @class vim.tohtml.state:vim.tohtml.state.global
+--- @class (private) vim.tohtml.state:vim.tohtml.state.global
 --- @field style vim.tohtml.styletable
 --- @field tabstop string|false
 --- @field opt vim.wo
@@ -48,20 +42,20 @@
 --- @field width integer
 --- @field buflen integer
 
---- @class vim.tohtml.styletable
+--- @class (private) vim.tohtml.styletable
 --- @field [integer] vim.tohtml.line (integer: (1-index, exclusive))
 
---- @class vim.tohtml.line
+--- @class (private) vim.tohtml.line
 --- @field virt_lines {[integer]:{[1]:string,[2]:integer}[]}
 --- @field pre_text string[][]
 --- @field hide? boolean
 --- @field [integer] vim.tohtml.cell? (integer: (1-index, exclusive))
 
---- @class vim.tohtml.cell
+--- @class (private) vim.tohtml.cell
 --- @field [1] integer[] start
 --- @field [2] integer[] close
---- @field [3]  any[][] virt_text
---- @field [4]  any[][] overlay_text
+--- @field [3] any[][] virt_text
+--- @field [4] any[][] overlay_text
 
 local HIDE_ID = -1
 -- stylua: ignore start
@@ -1319,14 +1313,29 @@ end
 
 local M = {}
 
+--- @class vim.tohtml.opt
+--- @inlinedoc
+---
+--- Title tag to set in the generated HTML code.
+--- (default: buffer name)
+--- @field title? string|false
+---
+--- Show line numbers.
+--- (default: `false`)
+--- @field number_lines? boolean
+---
+--- Fonts to use.
+--- (default: `guifont`)
+--- @field font? string[]|string
+---
+--- Width used for items which are either right aligned or repeat a character
+--- infinitely.
+--- (default: 'textwidth' if non-zero or window width otherwise)
+--- @field width? integer
+
 --- Converts the buffer shown in the window {winid} to HTML and returns the output as a list of string.
 --- @param winid? integer Window to convert (defaults to current window)
---- @param opt? vim.tohtml.opt (table) Optional parameters.
----               - title (string): Title tag to set in the generated HTML code (defaults to buffer name)
----               - number_lines (boolean): Show line numbers (defaults to `false`)
----               - font (string|string[]): Fonts to use (defaults to `guifont`)
----               - width (integer) Width used for items which are either right aligned or repeat a character infinitely
----                   (defaults to 'textwidth' if non-zero or window width otherwise)
+--- @param opt? vim.tohtml.opt Optional parameters.
 --- @return string[]
 function M.tohtml(winid, opt)
   return win_to_html(winid or 0, opt)
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index 4e39abb2be..d14007312e 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -190,6 +190,7 @@ function vim._os_proc_children(ppid)
   return children
 end
 
+--- @nodoc
 --- @class vim.inspect.Opts
 --- @field depth? integer
 --- @field newline? string
@@ -454,7 +455,7 @@ vim.cmd = setmetatable({}, {
   end,
 })
 
---- @class vim.var_accessor
+--- @class (private) vim.var_accessor
 --- @field [string] any
 --- @field [integer] vim.var_accessor
 
@@ -1048,7 +1049,7 @@ function vim.deprecate(name, alternative, version, plugin, backtrace)
   -- e.g., when planned to be removed in version = '0.12' (soft-deprecated since 0.10-dev),
   -- show warnings since 0.11, including 0.11-dev (hard_deprecated_since = 0.11-dev).
   if plugin == 'Nvim' then
-    local current_version = vim.version() ---@type Version
+    local current_version = vim.version() ---@type vim.Version
     local removal_version = assert(vim.version.parse(version))
     local is_hard_deprecated ---@type boolean
 
diff --git a/runtime/lua/vim/_inspector.lua b/runtime/lua/vim/_inspector.lua
index 9a073c32c4..a19d40c50d 100644
--- a/runtime/lua/vim/_inspector.lua
+++ b/runtime/lua/vim/_inspector.lua
@@ -1,8 +1,18 @@
----@class InspectorFilter
----@field syntax boolean include syntax based highlight groups (defaults to true)
----@field treesitter boolean include treesitter based highlight groups (defaults to true)
----@field extmarks boolean|"all" include extmarks. When `all`, then extmarks without a `hl_group` will also be included (defaults to true)
----@field semantic_tokens boolean include semantic token highlights (defaults to true)
+--- @class vim._inspector.Filter
+--- @inlinedoc
+---
+--- Include syntax based highlight groups (defaults to true)
+--- @field syntax boolean
+---
+--- Include treesitter based highlight groups (defaults to true)
+--- @field treesitter boolean
+---
+--- Include extmarks. When `all`, then extmarks without a `hl_group` will also be included.
+--- (default: true)
+--- @field extmarks boolean|"all"
+---
+--- Include semantic token highlights (defaults to true)
+--- @field semantic_tokens boolean
 local defaults = {
   syntax = true,
   treesitter = true,
@@ -17,11 +27,7 @@ local defaults = {
 ---@param bufnr? integer defaults to the current buffer
 ---@param row? integer row to inspect, 0-based. Defaults to the row of the current cursor
 ---@param col? integer col to inspect, 0-based. Defaults to the col of the current cursor
----@param filter? InspectorFilter (table) a table with key-value pairs to filter the items
----               - syntax (boolean): include syntax based highlight groups (defaults to true)
----               - treesitter (boolean): include treesitter based highlight groups (defaults to true)
----               - extmarks (boolean|"all"): include extmarks. When `all`, then extmarks without a `hl_group` will also be included (defaults to true)
----               - semantic_tokens (boolean): include semantic tokens (defaults to true)
+---@param filter? vim._inspector.Filter Table with key-value pairs to filter the items
 ---@return {treesitter:table,syntax:table,extmarks:table,semantic_tokens:table,buffer:integer,col:integer,row:integer} (table) a table with the following key-value pairs. Items are in "traversal order":
 ---               - treesitter: a list of treesitter captures
 ---               - syntax: a list of syntax groups
@@ -139,7 +145,7 @@ end
 ---@param bufnr? integer defaults to the current buffer
 ---@param row? integer row to inspect, 0-based. Defaults to the row of the current cursor
 ---@param col? integer col to inspect, 0-based. Defaults to the col of the current cursor
----@param filter? InspectorFilter (table) see |vim.inspect_pos()|
+---@param filter? vim._inspector.Filter (table) see |vim.inspect_pos()|
 function vim.show_pos(bufnr, row, col, filter)
   local items = vim.inspect_pos(bufnr, row, col, filter)
 
diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua
index 472162ecc1..4831989e1a 100644
--- a/runtime/lua/vim/_meta/builtin.lua
+++ b/runtime/lua/vim/_meta/builtin.lua
@@ -61,6 +61,7 @@ error('Cannot require a meta file')
 ---
 --- </pre>
 
+---@nodoc
 ---@class vim.NIL
 
 ---@type vim.NIL
diff --git a/runtime/lua/vim/_meta/lpeg.lua b/runtime/lua/vim/_meta/lpeg.lua
index 202c99f18c..1ce40f3340 100644
--- a/runtime/lua/vim/_meta/lpeg.lua
+++ b/runtime/lua/vim/_meta/lpeg.lua
@@ -21,6 +21,7 @@ error('Cannot require a meta file')
 
 vim.lpeg = {}
 
+--- @nodoc
 --- @class vim.lpeg.Pattern
 --- @operator unm: vim.lpeg.Pattern
 --- @operator add(vim.lpeg.Pattern): vim.lpeg.Pattern
@@ -167,6 +168,7 @@ function vim.lpeg.S(string) end
 --- @return vim.lpeg.Pattern
 function vim.lpeg.V(v) end
 
+--- @nodoc
 --- @class vim.lpeg.Locale
 --- @field alnum userdata
 --- @field alpha userdata
diff --git a/runtime/lua/vim/_meta/regex.lua b/runtime/lua/vim/_meta/regex.lua
index ab403b97e7..595ad96319 100644
--- a/runtime/lua/vim/_meta/regex.lua
+++ b/runtime/lua/vim/_meta/regex.lua
@@ -12,6 +12,7 @@
 --- @return vim.regex
 function vim.regex(re) end
 
+--- @nodoc
 --- @class vim.regex
 local regex = {} -- luacheck: no unused
 
diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua
index f1fed50c6d..bde9421552 100644
--- a/runtime/lua/vim/_options.lua
+++ b/runtime/lua/vim/_options.lua
@@ -797,6 +797,7 @@ end
 --- `vim.opt_global`.
 --- </pre>
 
+--- @nodoc
 --- @class vim.Option
 local Option = {} -- luacheck: no unused
 
diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua
index 49165c4db9..3979e5512c 100644
--- a/runtime/lua/vim/diagnostic.lua
+++ b/runtime/lua/vim/diagnostic.lua
@@ -2,18 +2,44 @@ local api, if_nil = vim.api, vim.F.if_nil
 
 local M = {}
 
+--- *diagnostic-structure*
+---
+--- Diagnostics use the same indexing as the rest of the Nvim API (i.e. 0-based
+--- rows and columns). |api-indexing|
 --- @class vim.Diagnostic
+---
+--- Buffer number
 --- @field bufnr? integer
---- @field lnum integer 0-indexed
---- @field end_lnum? integer 0-indexed
---- @field col integer 0-indexed
---- @field end_col? integer 0-indexed
+---
+--- The starting line of the diagnostic (0-indexed)
+--- @field lnum integer
+---
+--- The final line of the diagnostic (0-indexed)
+--- @field end_lnum? integer
+---
+--- The starting column of the diagnostic (0-indexed)
+--- @field col integer
+---
+--- The final column of the diagnostic (0-indexed)
+--- @field end_col? integer
+---
+--- The severity of the diagnostic |vim.diagnostic.severity|
 --- @field severity? vim.diagnostic.Severity
+---
+--- The diagnostic text
 --- @field message string
+---
+--- The source of the diagnostic
 --- @field source? string
+---
+--- The diagnostic code
 --- @field code? string|integer
+---
 --- @field _tags? { deprecated: boolean, unnecessary: boolean}
+---
+--- Arbitrary data plugins or users can add
 --- @field user_data? any arbitrary data plugins can add
+---
 --- @field namespace? integer
 
 --- @class vim.diagnostic.Opts
@@ -104,7 +130,7 @@ local global_diagnostic_options = {
   severity_sort = false,
 }
 
---- @class vim.diagnostic.Handler
+--- @class (private) vim.diagnostic.Handler
 --- @field show? fun(namespace: integer, bufnr: integer, diagnostics: vim.Diagnostic[], opts?: vim.diagnostic.OptsResolved)
 --- @field hide? fun(namespace:integer, bufnr:integer)
 
@@ -154,7 +180,7 @@ do
   })
 end
 
---- @class vim.diagnostic._extmark
+--- @class (private) vim.diagnostic._extmark
 --- @field [1] integer id
 --- @field [2] integer start
 --- @field [3] integer end
@@ -1018,31 +1044,52 @@ function M.get_next_pos(opts)
   return { next.lnum, next.col }
 end
 
+--- A table with the following keys:
 --- @class vim.diagnostic.GetOpts
+--- @inlinedoc
+---
+--- Limit diagnostics to the given namespace.
 --- @field namespace? integer
+---
+--- Limit diagnostics to the given line number.
 --- @field lnum? integer
+---
+--- See |diagnostic-severity|.
 --- @field severity? vim.diagnostic.SeverityFilter
 
+--- Configuration table with the following keys:
 --- @class vim.diagnostic.GotoOpts : vim.diagnostic.GetOpts
+--- @inlinedoc
+---
+--- Only consider diagnostics from the given namespace.
+--- @field namespace integer
+---
+--- Cursor position as a (row, col) tuple.
+--- See |nvim_win_get_cursor()|. Defaults to the current cursor position.
 --- @field cursor_position? {[1]:integer,[2]:integer}
+---
+--- Whether to loop around file or not. Similar to 'wrapscan'.
+--- (default: `true`)
 --- @field wrap? boolean
+---
+--- See |diagnostic-severity|.
+--- @field severity vim.diagnostic.Severity
+---
+--- If "true", call |vim.diagnostic.open_float()|
+--- after moving. If a table, pass the table as the {opts} parameter
+--- to |vim.diagnostic.open_float()|. Unless overridden, the float will show
+--- diagnostics at the new cursor position (as if "cursor" were passed to
+--- the "scope" option).
+--- (default: `true`)
 --- @field float? boolean|vim.diagnostic.Opts.Float
+---
+--- Window ID
+--- (default: `0`)
 --- @field win_id? integer
 
 --- Move to the next diagnostic.
 ---
----@param opts? vim.diagnostic.GotoOpts (table) Configuration table with the following keys:
----         - namespace: (integer) Only consider diagnostics from the given namespace.
----         - cursor_position: (cursor position) Cursor position as a (row, col) tuple.
----                          See |nvim_win_get_cursor()|. Defaults to the current cursor position.
----         - wrap: (boolean, default true) Whether to loop around file or not. Similar to 'wrapscan'.
----         - severity: See |diagnostic-severity|.
----         - float: (boolean or table, default true) If "true", call |vim.diagnostic.open_float()|
----                    after moving. If a table, pass the table as the {opts} parameter
----                    to |vim.diagnostic.open_float()|. Unless overridden, the float will show
----                    diagnostics at the new cursor position (as if "cursor" were passed to
----                    the "scope" option).
----         - win_id: (number, default 0) Window ID
+---@param opts? vim.diagnostic.GotoOpts
 function M.goto_next(opts)
   diagnostic_move_pos(opts, M.get_next_pos(opts))
 end
@@ -1789,38 +1836,54 @@ function M.reset(namespace, bufnr)
   end
 end
 
+--- Configuration table with the following keys:
 --- @class vim.diagnostic.setqflist.Opts
+--- @inlinedoc
+---
+--- Only add diagnostics from the given namespace.
 --- @field namespace? integer
+---
+--- Open quickfix list after setting.
+--- (default: `true`)
 --- @field open? boolean
+---
+--- Title of quickfix list. Defaults to "Diagnostics".
 --- @field title? string
+---
+--- See |diagnostic-severity|.
 --- @field severity? vim.diagnostic.Severity
 
 --- Add all diagnostics to the quickfix list.
 ---
----@param opts? vim.diagnostic.setqflist.Opts (table) Configuration table with the following keys:
----         - namespace: (number) Only add diagnostics from the given namespace.
----         - open: (boolean, default true) Open quickfix list after setting.
----         - title: (string) Title of quickfix list. Defaults to "Diagnostics".
----         - severity: See |diagnostic-severity|.
+---@param opts? vim.diagnostic.setqflist.Opts
 function M.setqflist(opts)
   set_list(false, opts)
 end
 
+---Configuration table with the following keys:
 --- @class vim.diagnostic.setloclist.Opts
+--- @inlinedoc
+---
+--- Only add diagnostics from the given namespace.
 --- @field namespace? integer
+---
+--- Window number to set location list for.
+--- (default: `0`)
+--- @field winnr? integer
+---
+--- Open the location list after setting.
+--- (default: `true`)
 --- @field open? boolean
+---
+--- Title of the location list. Defaults to "Diagnostics".
 --- @field title? string
+---
+--- See |diagnostic-severity|.
 --- @field severity? vim.diagnostic.Severity
---- @field winnr? integer
 
 --- Add buffer diagnostics to the location list.
 ---
----@param opts? vim.diagnostic.setloclist.Opts (table) Configuration table with the following keys:
----         - namespace: (number) Only add diagnostics from the given namespace.
----         - winnr: (number, default 0) Window number to set location list for.
----         - open: (boolean, default true) Open the location list after setting.
----         - title: (string) Title of the location list. Defaults to "Diagnostics".
----         - severity: See |diagnostic-severity|.
+---@param opts? vim.diagnostic.setloclist.Opts
 function M.setloclist(opts)
   set_list(true, opts)
 end
diff --git a/runtime/lua/vim/filetype.lua b/runtime/lua/vim/filetype.lua
index e7971d8916..fba76f93b2 100644
--- a/runtime/lua/vim/filetype.lua
+++ b/runtime/lua/vim/filetype.lua
@@ -2082,6 +2082,7 @@ local function normalize_path(path, as_pattern)
 end
 
 --- @class vim.filetype.add.filetypes
+--- @inlinedoc
 --- @field pattern? vim.filetype.mapping
 --- @field extension? vim.filetype.mapping
 --- @field filename? vim.filetype.mapping
@@ -2170,7 +2171,7 @@ end
 --- }
 --- ```
 ---
----@param filetypes vim.filetype.add.filetypes (table) A table containing new filetype maps (see example).
+---@param filetypes vim.filetype.add.filetypes A table containing new filetype maps (see example).
 function M.add(filetypes)
   for k, v in pairs(filetypes.extension or {}) do
     extension[k] = v
@@ -2272,8 +2273,23 @@ local function match_pattern(name, path, tail, pat)
 end
 
 --- @class vim.filetype.match.args
+--- @inlinedoc
+---
+--- Buffer number to use for matching. Mutually exclusive with {contents}
 --- @field buf? integer
+---
+--- Filename to use for matching. When {buf} is given,
+--- defaults to the filename of the given buffer number. The
+--- file need not actually exist in the filesystem. When used
+--- without {buf} only the name of the file is used for
+--- filetype matching. This may result in failure to detect
+--- the filetype in cases where the filename alone is not
+--- enough to disambiguate the filetype.
 --- @field filename? string
+---
+--- An array of lines representing file contents to use for
+--- matching. Can be used with {filename}. Mutually exclusive
+--- with {buf}.
 --- @field contents? string[]
 
 --- Perform filetype detection.
@@ -2305,20 +2321,8 @@ end
 --- vim.filetype.match({ contents = {'#!/usr/bin/env bash'} })
 --- ```
 ---
----@param args vim.filetype.match.args (table) Table specifying which matching strategy to use.
+---@param args vim.filetype.match.args Table specifying which matching strategy to use.
 ---                 Accepted keys are:
----                   * buf (number): Buffer number to use for matching. Mutually exclusive with
----                                   {contents}
----                   * filename (string): Filename to use for matching. When {buf} is given,
----                                        defaults to the filename of the given buffer number. The
----                                        file need not actually exist in the filesystem. When used
----                                        without {buf} only the name of the file is used for
----                                        filetype matching. This may result in failure to detect
----                                        the filetype in cases where the filename alone is not
----                                        enough to disambiguate the filetype.
----                   * contents (table): An array of lines representing file contents to use for
----                                       matching. Can be used with {filename}. Mutually exclusive
----                                       with {buf}.
 ---@return string|nil # If a match was found, the matched filetype.
 ---@return function|nil # A function that modifies buffer state when called (for example, to set some
 ---                     filetype specific buffer variables). The function accepts a buffer number as
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
index 0af5fc4f30..a47b35e991 100644
--- a/runtime/lua/vim/fs.lua
+++ b/runtime/lua/vim/fs.lua
@@ -147,11 +147,29 @@ function M.dir(path, opts)
   end)
 end
 
---- @class vim.fs.find.opts
+--- @class vim.fs.find.Opts
+--- @inlinedoc
+---
+--- Path to begin searching from. If
+--- omitted, the |current-directory| is used.
 --- @field path string
+---
+--- Search upward through parent directories.
+--- Otherwise, search through child directories (recursively).
+--- (default: `false`)
 --- @field upward boolean
+---
+--- Stop searching when this directory is reached.
+--- The directory itself is not searched.
 --- @field stop string
+---
+--- Find only items of the given type.
+--- If omitted, all items that match {names} are included.
 --- @field type string
+---
+--- Stop the search after finding this many matches.
+--- Use `math.huge` to place no limit on the number of matches.
+--- (default: `1`)
 --- @field limit number
 
 --- Find files or directories (or other items as specified by `opts.type`) in the given path.
@@ -194,23 +212,10 @@ end
 ---             - path: full path of the current item
 ---             The function should return `true` if the given item is considered a match.
 ---
----@param opts (table) Optional keyword arguments:
----                       - path (string): Path to begin searching from. If
----                              omitted, the |current-directory| is used.
----                       - upward (boolean, default false): If true, search
----                                upward through parent directories. Otherwise,
----                                search through child directories
----                                (recursively).
----                       - stop (string): Stop searching when this directory is
----                              reached. The directory itself is not searched.
----                       - type (string): Find only items of the given type.
----                               If omitted, all items that match {names} are included.
----                       - limit (number, default 1): Stop the search after
----                               finding this many matches. Use `math.huge` to
----                               place no limit on the number of matches.
+---@param opts vim.fs.find.Opts Optional keyword arguments:
 ---@return (string[]) # Normalized paths |vim.fs.normalize()| of all matching items
 function M.find(names, opts)
-  opts = opts or {} --[[@as vim.fs.find.opts]]
+  opts = opts or {}
   vim.validate({
     names = { names, { 's', 't', 'f' } },
     path = { opts.path, 's', true },
@@ -318,6 +323,13 @@ function M.find(names, opts)
   return matches
 end
 
+--- @class vim.fs.normalize.Opts
+--- @inlinedoc
+---
+--- Expand environment variables.
+--- (default: `true`)
+--- @field expand_env boolean
+
 --- Normalize a path to a standard format. A tilde (~) character at the
 --- beginning of the path is expanded to the user's home directory and any
 --- backslash (\) characters are converted to forward slashes (/). Environment
@@ -337,9 +349,8 @@ end
 --- ```
 ---
 ---@param path (string) Path to normalize
----@param opts table|nil Options:
----             - expand_env: boolean Expand environment variables (default: true)
----@return (string) Normalized path
+---@param opts? vim.fs.normalize.Opts
+---@return (string) : Normalized path
 function M.normalize(path, opts)
   opts = opts or {}
 
diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index 798428014d..09de969b5b 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -64,11 +64,13 @@
 --- In addition to the |vim.iter()| function, the |vim.iter| module provides
 --- convenience functions like |vim.iter.filter()| and |vim.iter.totable()|.
 
+---@nodoc
 ---@class IterMod
 ---@operator call:Iter
 
 local M = {}
 
+---@nodoc
 ---@class Iter
 local Iter = {}
 Iter.__index = Iter
@@ -77,6 +79,7 @@ Iter.__call = function(self)
 end
 
 --- Special case implementations for iterators on list tables.
+---@nodoc
 ---@class ListIter : Iter
 ---@field _table table Underlying table data
 ---@field _head number Index to the front of a table iterator
diff --git a/runtime/lua/vim/loader.lua b/runtime/lua/vim/loader.lua
index 5f3da55544..0d708ca1eb 100644
--- a/runtime/lua/vim/loader.lua
+++ b/runtime/lua/vim/loader.lua
@@ -10,16 +10,37 @@ local M = {}
 ---@alias CacheHash {mtime: {nsec: integer, sec: integer}, size: integer, type?: uv.aliases.fs_stat_types}
 ---@alias CacheEntry {hash:CacheHash, chunk:string}
 
----@class ModuleFindOpts
----@field all? boolean Search for all matches (defaults to `false`)
----@field rtp? boolean Search for modname in the runtime path (defaults to `true`)
----@field patterns? string[] Patterns to use (defaults to `{"/init.lua", ".lua"}`)
----@field paths? string[] Extra paths to search for modname
-
----@class ModuleInfo
----@field modpath string Path of the module
----@field modname string Name of the module
----@field stat? uv.uv_fs_t File stat of the module path
+--- @class vim.loader.find.Opts
+--- @inlinedoc
+---
+--- Search for modname in the runtime path.
+--- (default: `true`)
+--- @field rtp? boolean
+---
+--- Extra paths to search for modname
+--- (default: `{}`)
+--- @field paths? string[]
+---
+--- List of patterns to use when searching for modules.
+--- A pattern is a string added to the basename of the Lua module being searched.
+--- (default: `{"/init.lua", ".lua"}`)
+--- @field patterns? string[]
+---
+--- Search for all matches.
+--- (default: `false`)
+--- @field all? boolean
+
+--- @class vim.loader.ModuleInfo
+--- @inlinedoc
+---
+--- Path of the module
+--- @field modpath string
+---
+--- Name of the module
+--- @field modname string
+---
+--- The fs_stat of the module path. Won't be returned for `modname="*"`
+--- @field stat? uv.uv_fs_t
 
 ---@alias LoaderStats table<string, {total:number, time:number, [string]:number?}?>
 
@@ -29,14 +50,14 @@ M.path = vim.fn.stdpath('cache') .. '/luac'
 ---@nodoc
 M.enabled = false
 
----@class Loader
----@field _rtp string[]
----@field _rtp_pure string[]
----@field _rtp_key string
----@field _hashes? table<string, CacheHash>
+---@class (private) Loader
+---@field private _rtp string[]
+---@field private _rtp_pure string[]
+---@field private _rtp_key string
+---@field private _hashes? table<string, CacheHash>
 local Loader = {
   VERSION = 4,
-  ---@type table<string, table<string,ModuleInfo>>
+  ---@type table<string, table<string,vim.loader.ModuleInfo>>
   _indexed = {},
   ---@type table<string, string[]>
   _topmods = {},
@@ -270,17 +291,8 @@ end
 
 --- Finds Lua modules for the given module name.
 ---@param modname string Module name, or `"*"` to find the top-level modules instead
----@param opts? ModuleFindOpts (table) Options for finding a module:
----    - rtp: (boolean) Search for modname in the