Merge branch 'master' into dev

lua/acf/core/classes/helpers.lua

@@ -1,6 +1,7 @@
 local Classes = ACF.Classes
 
-
+--- Adds an sbox limit for this class
+--- @param Data {Name:string, Amount:number, Text:string}
 function Classes.AddSboxLimit(Data)
 	if CLIENT then return end
 	if ConVarExists("sbox_max" .. Data.Name) then return end

lua/acf/core/classes/object.lua

@@ -6,10 +6,14 @@ local Classes  = ACF.Classes
 local Stored   = {}
 local Queued   = {}
 
-
+--- Creates a new instance of the provided class  
+--- If the class has an "OnCalled" method defined, it will run that.
+--- @param Class table The class to create an instance of
+--- @return table # The newly created instance
 local function CreateInstance(Class)
 	local New = {}
 
+	-- This simulates "instantiation" among other things (https://www.lua.org/pil/13.4.1.html)
 	setmetatable(New, { __index = table.Copy(Class) })
 
 	if New.OnCalled then
@@ -19,6 +23,9 @@ local function CreateInstance(Class)
 	return New
 end
 
+--- Used to queue classes that are waiting for their base classes to be loaded
+--- @param ID string The id of the class to queue
+--- @param Base string The base class
 local function QueueBaseClass(ID, Base)
 	if not Queued[Base] then
 		Queued[Base] = { [ID] = true }
@@ -27,26 +34,31 @@ local function QueueBaseClass(ID, Base)
 	end
 end
 
+--- Updates/Initializes a metatable for a class and "parents" it to a base class
+--- @param Class table The class to be initialized/updated
+--- @param Base string The base class of the provided class
 local function AttachMetaTable(Class, Base)
 	local OldMeta = getmetatable(Class) or {}
 
 	if Base then
-		local BaseClass = Stored[Base]
+		local BaseClass = Stored[Base] -- Retrieve the base class from ID
 
 		if BaseClass then
-			Class.BaseClass = BaseClass
-			OldMeta.__index = BaseClass
+			Class.BaseClass = BaseClass -- Class' base class becomes BaseClass
+			OldMeta.__index = BaseClass -- Class inherits from BaseClass
 		else
 			QueueBaseClass(Class.ID, Base)
 		end
 	end
 
+	-- Update the "constructor" of the class to create an instance of the updated class
 	OldMeta.__call = function()
 		return CreateInstance(Class)
 	end
 
 	setmetatable(Class, OldMeta)
 
+	-- A tick later, classes will be guaranteed to have been loaded.
 	timer.Simple(0, function()
 		if Class.OnLoaded then
 			Class:OnLoaded()
@@ -58,6 +70,11 @@ local function AttachMetaTable(Class, Base)
 	end)
 end
 
+--- Creates a new object with the given ID, as a subclass of the Base class provided
+--- @param ID string The ID of the new sub class to add
+--- @param Base string The ID of the base class the sub class will inherit from
+--- @param Destiny table A table that the new object will be indexed into, with the ID as key
+--- @return table # The created class
 function Classes.AddObject(ID, Base, Destiny)
 	if not isstring(ID) then return end
 	if not istable(Destiny) then return end
@@ -67,8 +84,9 @@ function Classes.AddObject(ID, Base, Destiny)
 
 	Class.ID = ID
 
-	AttachMetaTable(Class, Base)
+	AttachMetaTable(Class, Base) -- Attach a metatable to "Class" with "Base" as parent
 
+	-- If this class is a base class for other class(es), attach metatables to all its sub classes with itself as base class.
 	if Queued[ID] then
 		for K in pairs(Queued[ID]) do
 			AttachMetaTable(Stored[K], ID)