feat(es_extended/common): annotations

[core]/es_extended/client/main.lua

@@ -387,7 +387,9 @@ if not Config.OxInventory then
 
             for _, v in ipairs(components) do
                 local component = ESX.GetWeaponComponent(name, v)
-                GiveWeaponComponentToWeaponObject(pickupObject, component.hash)
+                if component then
+                    GiveWeaponComponentToWeaponObject(pickupObject, component.hash)
+                end
             end
 
             setObjectProperties(pickupObject)

[core]/es_extended/client/modules/callback.lua

@@ -6,6 +6,7 @@ local clientCallbacks = {}
 ---@param eventName string
 ---@param callback function
 ---@param ... any
+---@return nil
 ESX.TriggerServerCallback = function(eventName, callback, ...)
     serverRequests[RequestId] = callback
 
@@ -25,6 +26,7 @@ end)
 
 ---@param eventName string
 ---@param callback function
+---@return nil
 ESX.RegisterClientCallback = function(eventName, callback)
     clientCallbacks[eventName] = callback
 end

[core]/es_extended/client/modules/streaming.lua

@@ -1,37 +1,68 @@
+---@param modelHash number | string
+---@param cb? function
+---@return number | nil
 function ESX.Streaming.RequestModel(modelHash, cb)
     modelHash = type(modelHash) == "number" and modelHash or joaat(modelHash)
+
     if not IsModelInCdimage(modelHash) then return end
+
 	RequestModel(modelHash)
 	while not HasModelLoaded(modelHash) do Wait(500) end
+
 	return cb and cb(modelHash) or modelHash
 end
 
+---@param textureDict string
+---@param cb? function
+---@return string | nil
 function ESX.Streaming.RequestStreamedTextureDict(textureDict, cb)
 	RequestStreamedTextureDict(textureDict, false)
+
 	while not HasStreamedTextureDictLoaded(textureDict) do Wait(500) end
+
 	return cb and cb(textureDict) or textureDict
 end
 
+---@param assetName string
+---@param cb? function
+---@return string | nil
 function ESX.Streaming.RequestNamedPtfxAsset(assetName, cb)
 	RequestNamedPtfxAsset(assetName)
+
 	while not HasNamedPtfxAssetLoaded(assetName) do Wait(500) end
+
 	return cb and cb(assetName) or assetName
 end
 
+---@param animSet string
+---@param cb? function
+---@return string | nil
 function ESX.Streaming.RequestAnimSet(animSet, cb)
 	RequestAnimSet(animSet)
+
 	while not HasAnimSetLoaded(animSet) do Wait(500) end
+
 	return cb and cb(animSet) or animSet
 end
 
+---@param animDict string
+---@param cb? function
+---@return string | nil
 function ESX.Streaming.RequestAnimDict(animDict, cb)
 	RequestAnimDict(animDict)
+
 	while not HasAnimDictLoaded(animDict) do Wait(500) end
+
 	return cb and cb(animDict) or animDict
 end
 
+---@param weaponHash number | string
+---@param cb? function
+---@return string | number | nil
 function ESX.Streaming.RequestWeaponAsset(weaponHash, cb)
 	RequestWeaponAsset(weaponHash, 31, 0)
+
 	while not HasWeaponAssetLoaded(weaponHash) do Wait(500) end
+
 	return cb and cb(weaponHash) or weaponHash
 end

[core]/es_extended/common/functions.lua

@@ -20,16 +20,21 @@ CreateThread(function()
     end
 end)
 
+---@param length number
+---@return string
 function ESX.GetRandomString(length)
     math.randomseed(GetGameTimer())
 
     return length > 0 and ESX.GetRandomString(length - 1) .. Charset[math.random(1, #Charset)] or ""
 end
 
+---@return table
 function ESX.GetConfig()
     return Config
 end
 
+---@param weaponName string
+---@return number, table
 function ESX.GetWeapon(weaponName)
     weaponName = string.upper(weaponName)
 
@@ -39,16 +44,22 @@ function ESX.GetWeapon(weaponName)
     return index, Config.Weapons[index]
 end
 
+---@param weaponHash number
+---@return table
 function ESX.GetWeaponFromHash(weaponHash)
     weaponHash = type(weaponHash) == "string" and joaat(weaponHash) or weaponHash
 
     return weaponsByHash[weaponHash]
 end
 
+---@param byHash boolean
+---@return table
 function ESX.GetWeaponList(byHash)
     return byHash and weaponsByHash or Config.Weapons
 end
 
+---@param weaponName string
+---@return string
 function ESX.GetWeaponLabel(weaponName)
     weaponName = string.upper(weaponName)
 
@@ -58,6 +69,9 @@ function ESX.GetWeaponLabel(weaponName)
     return Config.Weapons[index].label or ""
 end
 
+---@param weaponName string
+---@param weaponComponent string
+---@return table | nil
 function ESX.GetWeaponComponent(weaponName, weaponComponent)
     weaponName = string.upper(weaponName)
 
@@ -71,6 +85,9 @@ function ESX.GetWeaponComponent(weaponName, weaponComponent)
     end
 end
 
+---@param table table
+---@param nb? number
+---@return string
 function ESX.DumpTable(table, nb)
     if nb == nil then
         nb = 0
@@ -103,10 +120,16 @@ function ESX.DumpTable(table, nb)
     end
 end
 
+---@param value any
+---@param numDecimalPlaces? number
+---@return number
 function ESX.Round(value, numDecimalPlaces)
     return ESX.Math.Round(value, numDecimalPlaces)
 end
 
+---@param value string
+---@param ... any
+---@return boolean, string?
 function ESX.ValidateType(value, ...)
     local types = { ... }
     if #types == 0 then return true end
@@ -132,6 +155,8 @@ function ESX.ValidateType(value, ...)
     return true
 end
 
+---@param ... any
+---@return boolean
 function ESX.AssertType(...)
     local matches, errorMessage = ESX.ValidateType(...)
 

[core]/es_extended/common/modules/math.lua

@@ -1,5 +1,8 @@
 ESX.Math = {}
 
+---@param value number
+---@param numDecimalPlaces? number
+---@return number
 function ESX.Math.Round(value, numDecimalPlaces)
     if numDecimalPlaces then
         local power = 10 ^ numDecimalPlaces
@@ -10,20 +13,23 @@ function ESX.Math.Round(value, numDecimalPlaces)
 end
 
 -- credit http://richard.warburton.it
+---@param value number
+---@return string
 function ESX.Math.GroupDigits(value)
     local left, num, right = string.match(value, "^([^%d]*%d)(%d*)(.-)$")
 
     return left .. (num:reverse():gsub("(%d%d%d)", "%1" .. TranslateCap("locale_digit_grouping_symbol")):reverse()) .. right
 end
 
+---@param value string
+---@return string | nil
 function ESX.Math.Trim(value)
-    if value then
-        return (string.gsub(value, "^%s*(.-)%s*$", "%1"))
-    else
-        return nil
-    end
+    return (string.gsub(value, "^%s*(.-)%s*$", "%1"))
 end
 
+---@param minRange number
+---@param maxRange number
+---@return number
 function ESX.Math.Random(minRange, maxRange)
     math.randomseed(GetGameTimer())
     return math.random(minRange or 1, maxRange or 10)

[core]/es_extended/common/modules/table.lua

@@ -1,6 +1,8 @@
 ESX.Table = {}
 
 -- nil proof alternative to #table
+---@param t table
+---@return number
 function ESX.Table.SizeOf(t)
     local count = 0
 
@@ -11,6 +13,8 @@ function ESX.Table.SizeOf(t)
     return count
 end
 
+---@param t table
+---@return table
 function ESX.Table.Set(t)
     local set = {}
     for _, v in ipairs(t) do
@@ -19,6 +23,9 @@ function ESX.Table.Set(t)
     return set
 end
 
+---@param t table
+---@param value any
+---@return number
 function ESX.Table.IndexOf(t, value)
     for i = 1, #t, 1 do
         if t[i] == value then
@@ -29,6 +36,9 @@ function ESX.Table.IndexOf(t, value)
     return -1
 end
 
+---@param t table
+---@param value any
+---@return number
 function ESX.Table.LastIndexOf(t, value)
     for i = #t, 1, -1 do
         if t[i] == value then
@@ -39,6 +49,9 @@ function ESX.Table.LastIndexOf(t, value)
     return -1
 end
 
+---@param t table
+---@param cb function
+---@return any
 function ESX.Table.Find(t, cb)
     for i = 1, #t, 1 do
         if cb(t[i]) then
@@ -49,6 +62,9 @@ function ESX.Table.Find(t, cb)
     return nil
 end
 
+---@param t table
+---@param cb function
+---@return number
 function ESX.Table.FindIndex(t, cb)
     for i = 1, #t, 1 do
         if cb(t[i]) then
@@ -59,18 +75,24 @@ function ESX.Table.FindIndex(t, cb)
     return -1
 end
 
+---@param t table
+---@param cb function
+---@return table
 function ESX.Table.Filter(t, cb)
     local newTable = {}
 
     for i = 1, #t, 1 do
         if cb(t[i]) then
-            table.insert(newTable, t[i])
+            newTable[#newTable + 1] = t[i]
         end
     end
 
     return newTable
 end
 
+---@param t table
+---@param cb function
+---@return table
 function ESX.Table.Map(t, cb)
     local newTable = {}
 
@@ -81,6 +103,8 @@ function ESX.Table.Map(t, cb)
     return newTable
 end
 
+---@param t table
+---@return table
 function ESX.Table.Reverse(t)
     local newTable = {}
 
@@ -91,6 +115,8 @@ function ESX.Table.Reverse(t)
     return newTable
 end
 
+---@param t table
+---@return table
 function ESX.Table.Clone(t)
     if type(t) ~= "table" then
         return t
@@ -112,6 +138,9 @@ function ESX.Table.Clone(t)
     return target
 end
 
+---@param t1 table
+---@param t2 table
+---@return table
 function ESX.Table.Concat(t1, t2)
     local t3 = ESX.Table.Clone(t1)
 
@@ -122,6 +151,9 @@ function ESX.Table.Concat(t1, t2)
     return t3
 end
 
+---@param t table
+---@param sep string
+---@return string
 function ESX.Table.Join(t, sep)
     local str = ""
 
@@ -137,6 +169,9 @@ function ESX.Table.Join(t, sep)
 end
 
 -- Credits: https://github.com/JonasDev99/qb-garages/blob/b0335d67cb72a6b9ac60f62a87fb3946f5c2f33d/server/main.lua#L5
+---@param tab table
+---@param val any
+---@return boolean
 function ESX.Table.TableContains(tab, val)
     if type(val) == "table" then
         for _, value in pairs(tab) do
@@ -157,6 +192,9 @@ end
 
 -- Credit: https://stackoverflow.com/a/15706820
 -- Description: sort function for pairs
+---@param t table
+---@param order function
+---@return function
 function ESX.Table.Sort(t, order)
     -- collect the keys
     local keys = {}

[core]/es_extended/common/modules/timeout.lua

@@ -1,6 +1,9 @@
 local TimeoutCount = 0
 local CancelledTimeouts = {}
 
+---@param msec number
+---@param cb function
+---@return number
 ESX.SetTimeout = function(msec, cb)
     local id <const> = TimeoutCount + 1
 
@@ -18,6 +21,8 @@ ESX.SetTimeout = function(msec, cb)
     return id
 end
 
+---@param id number
+---@return nil
 ESX.ClearTimeout = function(id)
     CancelledTimeouts[id] = true
 end

[core]/es_extended/server/classes/player.lua

@@ -653,7 +653,6 @@ function CreateExtendedPlayer(playerId, identifier, group, accounts, inventory,
         local loadoutNum <const>, weapon <const> = self.getWeapon(weaponName)
 
         if weapon then
-            ---@type table
             local component <const> = ESX.GetWeaponComponent(weaponName, weaponComponent)
 
             if component then