diff --git a/lua/acf/core/classes/grouped.lua b/lua/acf/core/classes/grouped.lua index 1913cb67a..ee296ebaf 100644 --- a/lua/acf/core/classes/grouped.lua +++ b/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 # 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 # 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] diff --git a/lua/acf/core/classes/object.lua b/lua/acf/core/classes/object.lua index 7ebcf8706..7ae0b94eb 100644 --- a/lua/acf/core/classes/object.lua +++ b/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 diff --git a/lua/acf/core/classes/simple.lua b/lua/acf/core/classes/simple.lua index f244e3eb8..d6967d413 100644 --- a/lua/acf/core/classes/simple.lua +++ b/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 # 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 # An "array" (e.g. {class1,class2,...}) containing entries function Namespace.GetList() local Result = {} local Count = 0 @@ -62,6 +80,10 @@ 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 @@ -69,6 +91,9 @@ function Classes.AddSimpleFunctions(Namespace, Entries) 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]