docs(cache): more code comments

lua/lazy/core/cache.lua

@@ -1,3 +1,8 @@
+-- interop with the native Neovim cache
+if type(package.loaded["vim.cache"]) == "table" then
+  return package.loaded["vim.cache"]
+end
+
 local ffi = require("ffi")
 local uv = vim.loop
 
@@ -31,14 +36,16 @@ local Cache = {
   _loadfile = loadfile,
 }
 
+--- Tracks the time spent in a function
+---@private
 function M.track(stat, start)
   M.stats[stat] = M.stats[stat] or { total = 0, time = 0 }
   M.stats[stat].total = M.stats[stat].total + 1
   M.stats[stat].time = M.stats[stat].time + uv.hrtime() - start
 end
 
--- slightly faster/different version than vim.fs.normalize
+--- slightly faster/different version than vim.fs.normalize
--- we also need to have it here, since the cache will load vim.fs
+--- we also need to have it here, since the cache will load vim.fs
 ---@private
 function Cache.normalize(path)
   if path:sub(1, 1) == "~" then
@@ -52,9 +59,9 @@ function Cache.normalize(path)
   return path:sub(-1) == "/" and path:sub(1, -2) or path
 end
 
--- Gets the rtp excluding after directories.
+--- Gets the rtp excluding after directories.
--- The result is cached, and will be updated if the runtime path changes.
+--- The result is cached, and will be updated if the runtime path changes.
--- When called from a fast event, the cached value will be returned.
+--- When called from a fast event, the cached value will be returned.
 --- @return string[] rtp, boolean updated
 ---@private
 function Cache.get_rtp()
@@ -81,7 +88,7 @@ function Cache.get_rtp()
   return Cache._rtp, updated
 end
 
--- Returns the cache file name
+--- Returns the cache file name
 ---@param name string can be a module name, or a file name
 ---@return string file_name
 ---@private
@@ -90,7 +97,7 @@ function Cache.cache_file(name)
   return ret:sub(-4) == ".lua" and (ret .. "c") or (ret .. ".luac")
 end
 
--- Saves the cache entry for a given module or file
+--- Saves the cache entry for a given module or file
 ---@param name string module name or filename
 ---@param entry CacheEntry
 ---@private
@@ -108,7 +115,7 @@ function Cache.write(name, entry)
   uv.fs_close(f)
 end
 
--- Loads the cache entry for a given module or file
+--- Loads the cache entry for a given module or file
 ---@param name string module name or filename
 ---@return CacheEntry?
 ---@private
@@ -135,7 +142,7 @@ function Cache.read(name)
   M.track("read", start)
 end
 
--- The `package.loaders` loader for lua files using the cache.
+--- The `package.loaders` loader for lua files using the cache.
 ---@param modname string module name
 ---@return string|function
 ---@private
@@ -151,7 +158,7 @@ function Cache.loader(modname)
   return "\ncache_loader: module " .. modname .. " not found"
 end
 
--- The `package.loaders` loader for libs
+--- The `package.loaders` loader for libs
 ---@param modname string module name
 ---@return string|function
 ---@private
@@ -175,7 +182,7 @@ function Cache.loader_lib(modname)
   return "\ncache_loader_lib: module " .. modname .. " not found"
 end
 
--- `loadfile` using the cache
+--- `loadfile` using the cache
 ---@param filename? string
 ---@param mode? "b"|"t"|"bt"
 ---@param env? table
@@ -190,10 +197,10 @@ function Cache.loadfile(filename, mode, env)
   return chunk, err
 end
 
--- Checks whether two cache hashes are the same based on:
+--- Checks whether two cache hashes are the same based on:
--- * file size
+--- * file size
--- * mtime in seconds
+--- * mtime in seconds
--- * mtime in nanoseconds
+--- * mtime in nanoseconds
 ---@param h1 CacheHash
 ---@param h2 CacheHash
 ---@private
@@ -201,11 +208,14 @@ function Cache.eq(h1, h2)
   return h1 and h2 and h1.size == h2.size and h1.mtime.sec == h2.mtime.sec and h1.mtime.nsec == h2.mtime.nsec
 end
 
--- Loads the given module path using the cache
+--- Loads the given module path using the cache
 ---@param modpath string
----@param opts? {hash?: CacheHash, mode?: "b"|"t"|"bt", env?:table}
+---@param opts? {hash?: CacheHash, mode?: "b"|"t"|"bt", env?:table} (table|nil) Options for loading the module:
+---    - hash: (table) the hash of the file to load if it is already known. (defaults to `vim.loop.fs_stat({modpath})`)
+---    - mode: (string) the mode to load the module with. "b"|"t"|"bt" (defaults to `nil`)
+---    - env: (table) the environment to load the module in. (defaults to `nil`)
+---@see |luaL_loadfile()|
 ---@return function?, string? error_message
----@private
 function M.load(modpath, opts)
   local start = uv.hrtime()
 
@@ -242,10 +252,13 @@ function M.load(modpath, opts)
   return chunk, err
 end
 
--- Finds the module path for the given module name
+--- Finds the module path for the given module name
 ---@param modname string
----@param opts? CacheFindOpts
+---@param opts? CacheFindOpts (table|nil) Options for finding a module:
----@return string? modpath, CacheHash? hash
+---    - rtp: (boolean) Search for modname in the runtime path (defaults to `true`)
+---    - patterns: (string[]) Paterns to use (defaults to `{"/init.lua", ".lua"}`)
+---    - paths: (string[]) Extra paths to search for modname (defaults to `{}`)
+---@return string? modpath, CacheHash? hash (string|nil) modpath for the module
 function M.find(modname, opts)
   local start = uv.hrtime()
   opts = opts or {}
@@ -319,16 +332,16 @@ function M.find(modname, opts)
 end
 
 --- Resets the topmods cache for the path
----@param path string
+---@param path string path to reset
 function M.reset(path)
   Cache._indexed[Cache.normalize(path)] = nil
 end
 
--- Enables the cache:
+--- Enables the cache:
--- * override loadfile
+--- * override loadfile
--- * adds the lua loader
+--- * adds the lua loader
--- * adds the libs loader
+--- * adds the libs loader
--- * remove the Neovim loader
+--- * remove the Neovim loader
 function M.enable()
   if M.enabled then
     return
@@ -353,9 +366,9 @@ function M.enable()
   -- This will make sure we can properly load new top-level lua modules
 end
 
--- Disables the cache:
+--- Disables the cache:
--- * removes the cache loaders
+--- * removes the cache loaders
--- * adds the Neovim loader
+--- * adds the Neovim loader
 function M.disable()
   if not M.enabled then
     return
@@ -372,7 +385,8 @@ function M.disable()
   table.insert(package.loaders, 2, vim._load_package)
 end
 
--- Return the top-level `/lua/*` modules for this path
+--- Return the top-level `/lua/*` modules for this path
+---@param path string path to check for top-level lua modules
 ---@return string[]
 function M.lsmod(path)
   if not Cache._indexed[path] then
@@ -409,7 +423,7 @@ function M.lsmod(path)
   return Cache._indexed[path]
 end
 
--- Debug function that wrapps all loaders and tracks stats
+--- Debug function that wrapps all loaders and tracks stats
 function M.profile_loaders()
   for l, loader in pairs(package.loaders) do
     local loc = debug.getinfo(loader, "Sn").source:sub(2)
@@ -423,7 +437,7 @@ function M.profile_loaders()
   end
 end
 
--- Prints all cache stats
+--- Prints all cache stats
 function M.inspect()
   ---@private
   local function ms(nsec)