From d2bea9eefd1d99d3bfeebd0c848fa62488ef0461 Mon Sep 17 00:00:00 2001
From: Folke Lemaitre <folke.lemaitre@gmail.com>
Date: Sat, 22 Jun 2024 22:30:20 +0200
Subject: [PATCH] docs: added doc comments

---
 lua/lazy/core/fragments.lua |  7 +++++++
 lua/lazy/core/meta.lua      | 22 +++++++++++++++++++++-
 lua/lazy/core/plugin.lua    |  2 +-
 3 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/lua/lazy/core/fragments.lua b/lua/lazy/core/fragments.lua
index 7096f55..1ca018c 100644
--- a/lua/lazy/core/fragments.lua
+++ b/lua/lazy/core/fragments.lua
@@ -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()
diff --git a/lua/lazy/core/meta.lua b/lua/lazy/core/meta.lua
index 9c40238..35006d7 100644
--- a/lua/lazy/core/meta.lua
+++ b/lua/lazy/core/meta.lua
@@ -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()
 
diff --git a/lua/lazy/core/plugin.lua b/lua/lazy/core/plugin.lua
index 6aec6f1..355d3d5 100644
--- a/lua/lazy/core/plugin.lua
+++ b/lua/lazy/core/plugin.lua
@@ -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