docs: added doc comments

This commit is contained in:
Folke Lemaitre 2024-06-22 22:30:20 +02:00
parent a2b05c38cc
commit c37e1a42fd
3 changed files with 29 additions and 2 deletions

View File

@ -9,6 +9,9 @@ local function next_id()
return M._fid
end
--- This class is used to manage the fragments of a plugin spec.
--- It keeps track of the fragments and their relations to other fragments.
--- A fragment can be a dependency (dependencies) or a child (specs) of another fragment.
---@class LazyFragments
---@field fragments table<number, LazyFragment>
---@field frag_stack number[]
@ -34,6 +37,8 @@ function F:get(id)
return self.fragments[id]
end
--- Remove a fragment and all its children.
--- This will also remove the fragment from its parent's children list.
---@param id number
function F:del(id)
-- del fragment
@ -73,6 +78,8 @@ function F:del(id)
self.fragments[id] = nil
end
--- Add a fragment to the fragments list.
--- This also resolves its name, url, dir, dependencies and child specs.
---@param plugin LazyPluginSpec
function F:add(plugin)
local id = next_id()

View File

@ -1,6 +1,8 @@
local Config = require("lazy.core.config")
local Util = require("lazy.core.util")
--- This class is used to manage the plugins.
--- A plugin is a collection of fragments that are related to each other.
---@class LazyMeta
---@field plugins table<string, LazyPlugin>
---@field str_to_meta table<string, LazyPlugin>
@ -23,6 +25,7 @@ function M.new(spec)
return self
end
--- Remove a plugin and all its fragments.
---@param name string
function M:del(name)
local meta = self.plugins[name]
@ -35,6 +38,9 @@ function M:del(name)
self.plugins[name] = nil
end
--- Add a fragment to a plugin.
--- This will create a new plugin if it does not exist.
--- It also keeps track of renames.
---@param plugin LazyPluginSpec
function M:add(plugin)
local fragment = self.fragments:add(plugin)
@ -73,6 +79,8 @@ function M:add(plugin)
self.dirty[meta.name] = true
end
--- Rebuild all plugins based on dirty fragments,
--- or dirty plugins. Will remove plugins that no longer have fragments.
function M:rebuild()
for fid in pairs(self.fragments.dirty) do
local meta = self.frag_to_meta[fid]
@ -101,6 +109,9 @@ function M:rebuild()
end
end
--- Rebuild a single plugin.
--- This will resolve the plugin based on its fragments using metatables.
--- This also resolves dependencies, dep, optional, dir, dev, and url.
---@param name string
function M:_rebuild(name)
local plugin = self.plugins[name]
@ -161,18 +172,23 @@ function M:_rebuild(name)
plugin.dir = plugin.dir or Config.options.root .. "/" .. plugin.name
end
-- dependencies
if #plugin.dependencies == 0 and not super.dependencies then
plugin.dependencies = nil
end
-- optional
if not plugin.optional and not super.optional then
plugin.optional = nil
end
setmetatable(plugin, { __index = super })
self.dirty[plugin.name] = nil
return plugin
end
--- Disable a plugin.
---@param plugin LazyPlugin
function M:disable(plugin)
plugin._.kind = "disabled"
@ -180,6 +196,7 @@ function M:disable(plugin)
self.spec.disabled[plugin.name] = plugin
end
--- Check if a plugin should be disabled, but ignore uninstalling it.
function M:fix_cond()
for _, plugin in pairs(self.plugins) do
local cond = plugin.cond
@ -203,6 +220,7 @@ function M:fix_cond()
end
end
--- Removes plugins for which all its fragments are optional.
function M:fix_optional()
if self.spec.optional then
return 0
@ -218,6 +236,7 @@ function M:fix_optional()
return changes
end
--- Removes plugins that are disabled.
function M:fix_disabled()
local changes = 0
for _, plugin in pairs(self.plugins) do
@ -230,7 +249,8 @@ function M:fix_disabled()
return changes
end
function M:fix()
--- Resolve all plugins, based on cond, enabled and optional.
function M:resolve()
Util.track("resolve plugins")
self:rebuild()

View File

@ -50,7 +50,7 @@ end
function Spec:parse(spec)
self:normalize(spec)
self.meta:fix()
self.meta:resolve()
end
-- PERF: optimized code to get package name without using lua patterns