From 0765f333969e82973e6a8a9c20895fb1ad29699f Mon Sep 17 00:00:00 2001 From: LengthenedGradient <109800352+LengthenedGradient@users.noreply.github.com> Date: Wed, 10 Apr 2024 19:32:06 -0400 Subject: [PATCH 1/5] Additional class documentation --- lua/acf/core/classes/grouped.lua | 19 ++++++++++++++++++- lua/acf/core/classes/object.lua | 2 +- lua/acf/core/classes/simple.lua | 10 +++++++++- 3 files changed, 28 insertions(+), 3 deletions(-) diff --git a/lua/acf/core/classes/grouped.lua b/lua/acf/core/classes/grouped.lua index 1913cb67a..8b52af028 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 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 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,10 @@ function Classes.AddGroupItem(ID, GroupID, Destiny, Data) return Class end +--- Gets a group or group item given its ID and the namespace it's stored in +--- @param Namespace string The table to store the group in +--- @param ID string The ID of the group +--- @return table | nil # The group or group item if found function Classes.GetGroup(Namespace, ID) if not istable(Namespace) then return end if not isstring(ID) then return end @@ -80,6 +94,9 @@ function Classes.GetGroup(Namespace, ID) end end +--- Indexes the groups stored in Entries into a new Namespace, with helper functions +--- @param Namespace table The namespace to store the groups under +--- @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 diff --git a/lua/acf/core/classes/object.lua b/lua/acf/core/classes/object.lua index 7ebcf8706..96f426fc9 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 # 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..29d4d9f1a 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 +--- @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 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,6 +34,9 @@ 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 namespace to store the simple classes under +--- @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 From deab3bc718e6ece5be14f7cb4229f18ccc416b9c Mon Sep 17 00:00:00 2001 From: LengthenedGradient <109800352+LengthenedGradient@users.noreply.github.com> Date: Fri, 12 Apr 2024 00:34:01 -0400 Subject: [PATCH 2/5] Fix Type Annotations and Comments --- lua/acf/core/classes/grouped.lua | 10 +++++----- lua/acf/core/classes/object.lua | 2 +- lua/acf/core/classes/simple.lua | 6 +++--- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/lua/acf/core/classes/grouped.lua b/lua/acf/core/classes/grouped.lua index 8b52af028..e684b6c9d 100644 --- a/lua/acf/core/classes/grouped.lua +++ b/lua/acf/core/classes/grouped.lua @@ -8,7 +8,7 @@ local Classes = ACF.Classes --- @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 Group The created 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 @@ -41,7 +41,7 @@ end --- @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 Class The created 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 @@ -73,8 +73,8 @@ function Classes.AddGroupItem(ID, GroupID, Destiny, Data) return Class end ---- Gets a group or group item given its ID and the namespace it's stored in ---- @param Namespace string The table to store the group in +--- Gets a group given its ID and the namespace it's stored in +--- @param Namespace string The namespace to lookup the group in --- @param ID string The ID of the group --- @return table | nil # The group or group item if found function Classes.GetGroup(Namespace, ID) @@ -95,7 +95,7 @@ function Classes.GetGroup(Namespace, ID) end --- Indexes the groups stored in Entries into a new Namespace, with helper functions ---- @param Namespace table The namespace to store the groups under +--- @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 diff --git a/lua/acf/core/classes/object.lua b/lua/acf/core/classes/object.lua index 96f426fc9..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 object +--- @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 29d4d9f1a..d6a04301f 100644 --- a/lua/acf/core/classes/simple.lua +++ b/lua/acf/core/classes/simple.lua @@ -5,11 +5,11 @@ local istable = istable local Classes = ACF.Classes --- Registers a simple class ---- Similar to Classes.AddObject +--- 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 Class The created 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 @@ -35,7 +35,7 @@ function Classes.AddSimple(ID, Destiny, Data) end --- Indexes the simple classes stored in Entries into a new Namespace, with helper functions ---- @param Namespace table The namespace to store the simple classes under +--- @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 From 1dfb4e081f20c8677442a592012328bcb1879a34 Mon Sep 17 00:00:00 2001 From: LengthenedGradient <109800352+LengthenedGradient@users.noreply.github.com> Date: Fri, 12 Apr 2024 03:19:05 -0400 Subject: [PATCH 3/5] Fix Return Description Of GetGroup --- lua/acf/core/classes/grouped.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lua/acf/core/classes/grouped.lua b/lua/acf/core/classes/grouped.lua index e684b6c9d..be94bcf33 100644 --- a/lua/acf/core/classes/grouped.lua +++ b/lua/acf/core/classes/grouped.lua @@ -76,7 +76,7 @@ end --- Gets a group given its ID and the namespace it's stored in --- @param Namespace string The namespace to lookup the group in --- @param ID string The ID of the group ---- @return table | nil # The group or group item if found +--- @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 From b112372d5855e048014bd738a947e6ee7e1361c4 Mon Sep 17 00:00:00 2001 From: LengthenedGradient <109800352+LengthenedGradient@users.noreply.github.com> Date: Sat, 13 Apr 2024 02:48:03 -0400 Subject: [PATCH 4/5] Add Documentation To Namespace Helper Functions --- lua/acf/core/classes/grouped.lua | 28 ++++++++++++++++++++++++++-- lua/acf/core/classes/simple.lua | 19 ++++++++++++++++++- 2 files changed, 44 insertions(+), 3 deletions(-) diff --git a/lua/acf/core/classes/grouped.lua b/lua/acf/core/classes/grouped.lua index be94bcf33..ee296ebaf 100644 --- a/lua/acf/core/classes/grouped.lua +++ b/lua/acf/core/classes/grouped.lua @@ -73,9 +73,10 @@ function Classes.AddGroupItem(ID, GroupID, Destiny, Data) return Class end ---- Gets a group given its ID and the namespace it's stored in +--- 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 +--- @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 @@ -101,9 +102,15 @@ 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] @@ -112,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] @@ -126,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] @@ -141,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] @@ -153,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/simple.lua b/lua/acf/core/classes/simple.lua index d6a04301f..7b636b69c 100644 --- a/lua/acf/core/classes/simple.lua +++ b/lua/acf/core/classes/simple.lua @@ -41,11 +41,18 @@ function Classes.AddSimpleFunctions(Namespace, Entries) if not istable(Namespace) then return end if not istable(Entries) then return end - -- Getter + -- Getters + + --- Gets the (object/simple class/group) from the namespace with the given ID + --- @param ID string The ID of the (object/simple class/group) + --- @return table | nil # The (object/simple class/group) function Namespace.Get(ID) return isstring(ID) and Entries[ID] or nil end + --- Gets all the (objects/simple classes/groups) belonging to the namespace + --- If aliases exist in the namespace, they will be ignored in the returned table + --- @return table # A table mapping the an (object/simple class/group)'s ID to itself function Namespace.GetEntries() local Result = {} @@ -56,6 +63,9 @@ function Classes.AddSimpleFunctions(Namespace, Entries) return Result end + --- Gets all the (objects/simple classes/groups) belonging to 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 (objects/simple classes/groups) function Namespace.GetList() local Result = {} local Count = 0 @@ -70,6 +80,10 @@ function Classes.AddSimpleFunctions(Namespace, Entries) end -- Aliases + + --- Adds an alias to a (objects/simple classes/groups) + --- @param ID string The ID of the (objects/simple classes/groups) 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 @@ -77,6 +91,9 @@ function Classes.AddSimpleFunctions(Namespace, Entries) Entries[Alias] = Entries[ID] end + --- Checks whether an ID is an alias + --- @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] From dd059c1eaa7c20d391bef56f57bd1947f0cb9ff7 Mon Sep 17 00:00:00 2001 From: LengthenedGradient <109800352+LengthenedGradient@users.noreply.github.com> Date: Sat, 13 Apr 2024 10:31:34 -0400 Subject: [PATCH 5/5] Replaced "object/simple class/group" with "entries" --- lua/acf/core/classes/simple.lua | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/lua/acf/core/classes/simple.lua b/lua/acf/core/classes/simple.lua index 7b636b69c..d6967d413 100644 --- a/lua/acf/core/classes/simple.lua +++ b/lua/acf/core/classes/simple.lua @@ -34,7 +34,7 @@ function Classes.AddSimple(ID, Destiny, Data) return Class end ---- Indexes the simple classes stored in Entries into a new Namespace, with helper functions +--- 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) @@ -43,16 +43,16 @@ function Classes.AddSimpleFunctions(Namespace, Entries) -- Getters - --- Gets the (object/simple class/group) from the namespace with the given ID - --- @param ID string The ID of the (object/simple class/group) - --- @return table | nil # The (object/simple class/group) + --- 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 (objects/simple classes/groups) belonging to the namespace + --- 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 (object/simple class/group)'s ID to itself + --- @return table # A table mapping the an entry's ID to itself function Namespace.GetEntries() local Result = {} @@ -63,9 +63,9 @@ function Classes.AddSimpleFunctions(Namespace, Entries) return Result end - --- Gets all the (objects/simple classes/groups) belonging to the namespace + --- 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 (objects/simple classes/groups) + --- @return table # An "array" (e.g. {class1,class2,...}) containing entries function Namespace.GetList() local Result = {} local Count = 0 @@ -81,8 +81,8 @@ function Classes.AddSimpleFunctions(Namespace, Entries) -- Aliases - --- Adds an alias to a (objects/simple classes/groups) - --- @param ID string The ID of the (objects/simple classes/groups) to apply an alias to + --- 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 @@ -91,7 +91,7 @@ function Classes.AddSimpleFunctions(Namespace, Entries) Entries[Alias] = Entries[ID] end - --- Checks whether an ID is an alias + --- 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)