Merge pull request #399 from LengthenedGradient/Entity-Documentation

Additional class documentation

lua/acf/core/classes/grouped.lua

@@ -4,7 +4,11 @@ local isstring = isstring
 local istable  = istable
 local Classes  = ACF.Classes
 
-
+--- Registers a group
+--- @param ID string The ID of the group
+--- @param Destiny table The table to store the group in
+--- @param Data table The data of the group
+--- @return table | nil Group The created group
 function Classes.AddGroup(ID, Destiny, Data)
 	if not isstring(ID) then return end
 	if not istable(Destiny) then return end
@@ -32,6 +36,12 @@ function Classes.AddGroup(ID, Destiny, Data)
 	return Group
 end
 
+--- Registers a group item under a group
+--- @param ID string The ID of the item to add to the group
+--- @param GroupID string The ID of the group previously created using Class.AddGroup
+--- @param Destiny string The table to store the group item in (should be the same as the group)
+--- @param Data table The data of the group item
+--- @return table | nil Class The created group item
 function Classes.AddGroupItem(ID, GroupID, Destiny, Data)
 	if not isstring(ID) then return end
 	if not isstring(GroupID) then return end
@@ -63,6 +73,11 @@ function Classes.AddGroupItem(ID, GroupID, Destiny, Data)
 	return Class
 end
 
+--- Gets a group given its ID and the namespace it's stored in  
+--- If no such group exists, it will instead check for a group that has a group item with the given ID
+--- @param Namespace string The namespace to lookup the group in
+--- @param ID string The ID of the group, or the ID of a group item
+--- @return table | nil # The group if found
 function Classes.GetGroup(Namespace, ID)
 	if not istable(Namespace) then return end
 	if not isstring(ID) then return end
@@ -80,13 +95,22 @@ function Classes.GetGroup(Namespace, ID)
 	end
 end
 
+--- Indexes the groups stored in Entries into a new Namespace, with helper functions
+--- @param Namespace table The table that will receive the new functions
+--- @param Entries table The table storing groups
 function Classes.AddGroupedFunctions(Namespace, Entries)
 	if not istable(Namespace) then return end
 	if not istable(Entries) then return end
 
+	-- Note that all the functions for simple class namespaces apply too.
 	Classes.AddSimpleFunctions(Namespace, Entries)
 
 	-- Getters
+
+	--- Gets a group item from a group in the namespace
+	--- @param ClassID string The ID of the group
+	--- @param ID string The ID of the group item
+	--- @return table | nil # A group item
 	function Namespace.GetItem(ClassID, ID)
 		local Group = isstring(ClassID) and Entries[ClassID]
 
@@ -95,6 +119,10 @@ function Classes.AddGroupedFunctions(Namespace, Entries)
 		return isstring(ID) and Group.Lookup[ID] or nil
 	end
 
+	--- Gets all the group items for a given group in the namespace  
+	--- If aliases exist in the namespace, they will be ignored in the returned table
+	--- @param ClassID string The ID of the group to explore
+	--- @return table<string,table> # A table mapping item's IDs to themselves
 	function Namespace.GetItemEntries(ClassID)
 		local Group = isstring(ClassID) and Entries[ClassID]
 
@@ -109,6 +137,10 @@ function Classes.AddGroupedFunctions(Namespace, Entries)
 		return Result
 	end
 
+	--- Gets all the group items for a given group in the namespace  
+	--- If aliases exist in the namespace, they will be included in the returned table
+	--- @param ClassID string The ID of the group to explore
+	--- @return table<number, table> # An "array" (e.g. {class1,class2,...}) containing group items.
 	function Namespace.GetItemList(ClassID)
 		local Group = isstring(ClassID) and Entries[ClassID]
 
@@ -124,6 +156,11 @@ function Classes.AddGroupedFunctions(Namespace, Entries)
 	end
 
 	-- Aliases
+
+	--- Adds an alias to a group item
+	--- @param GroupID string # The ID of the group the group item belongs to
+	--- @param ID string # The ID of the group item to make an alias of
+	--- @param Alias string # The alias to apply to the given group item
 	function Namespace.AddItemAlias(GroupID, ID, Alias)
 		local Group = isstring(GroupID) and Entries[GroupID]
 
@@ -136,6 +173,10 @@ function Classes.AddGroupedFunctions(Namespace, Entries)
 		Lookup[Alias] = Lookup[ID]
 	end
 
+	--- Checks whether an ID is an alias of a group item
+	--- @param GroupID string # The ID of the group the group item belongs to
+	--- @param ID string # The ID to check
+	--- @return boolean # Whether the ID is an alias of a group item
 	function Namespace.IsItemAlias(GroupID, ID)
 		local Group = isstring(GroupID) and Entries[GroupID]
 

lua/acf/core/classes/object.lua

@@ -74,7 +74,7 @@ end
 --- @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
+--- @return table | nil # The created object
 function Classes.AddObject(ID, Base, Destiny)
 	if not isstring(ID) then return end
 	if not istable(Destiny) then return end

lua/acf/core/classes/simple.lua

@@ -4,7 +4,12 @@ local isstring = isstring
 local istable  = istable
 local Classes  = ACF.Classes
 
-
+--- Registers a simple class 
+--- Similar to Classes.AddObject, except more intended to purely store data (e.g. fuel types) (try not to put methods in these).
+--- @param ID string The ID of the simple class to add
+--- @param Destiny table The table to store the simple class in
+--- @param Data table The data of the simple class
+--- @return table | nil Class The created simple class
 function Classes.AddSimple(ID, Destiny, Data)
 	if not isstring(ID) then return end
 	if not istable(Destiny) then return end
@@ -29,15 +34,25 @@ function Classes.AddSimple(ID, Destiny, Data)
 	return Class
 end
 
+--- Indexes the simple classes stored in "Entries" into a new Namespace, with helper functions
+--- @param Namespace table The table that will receive the new functions
+--- @param Entries table The table storing simple classes
 function Classes.AddSimpleFunctions(Namespace, Entries)
 	if not istable(Namespace) then return end
 	if not istable(Entries) then return end
 
-	-- Getter
+	-- Getters
+
+	--- Gets the entry from the namespace with the given ID
+	--- @param ID string The ID of the entry
+	--- @return table | nil # The entry
 	function Namespace.Get(ID)
 		return isstring(ID) and Entries[ID] or nil
 	end
 
+	--- Gets all the entries in the namespace  
+	--- If aliases exist in the namespace, they will be ignored in the returned table
+	--- @return table<string,table> # A table mapping the an entry's ID to itself 
 	function Namespace.GetEntries()
 		local Result = {}
 
@@ -48,6 +63,9 @@ function Classes.AddSimpleFunctions(Namespace, Entries)
 		return Result
 	end
 
+	--- Gets all the entries in the namespace  
+	--- If aliases exist in the namespace, they will be included in the returned table
+	--- @return table<number,table> # An "array" (e.g. {class1,class2,...}) containing entries
 	function Namespace.GetList()
 		local Result = {}
 		local Count  = 0
@@ -62,13 +80,20 @@ function Classes.AddSimpleFunctions(Namespace, Entries)
 	end
 
 	-- Aliases
+
+	--- Adds an alias to a entry in the namespace
+	--- @param ID string The ID of the entry to apply an alias to
+	--- @param Alias string The Alias to map to the given ID
 	function Namespace.AddAlias(ID, Alias)
 		if not isstring(ID) then return end
 		if not isstring(Alias) then return end
 
 		Entries[Alias] = Entries[ID]
 	end
 
+	--- Checks whether an ID is an alias of an entry in the namespace
+	--- @param ID string The ID to check
+	--- @return boolean # Whether the ID is an alias
 	function Namespace.IsAlias(ID)
 		local Data = isstring(ID) and Entries[ID]