Add documentation (luadoc) to functions

server/functions.lua

@@ -8,12 +8,19 @@ QBCore.UsableItems = {}
 -- ex: local player = QBCore.Functions.GetPlayer(source)
 -- ex: local example = player.Functions.functionname(parameter)
 
+---Gets the coordinates of an entity
+---@param entity number
+---@return vector4
 function QBCore.Functions.GetCoords(entity)
     local coords = GetEntityCoords(entity, false)
     local heading = GetEntityHeading(entity)
     return vector4(coords.x, coords.y, coords.z, heading)
 end
 
+---Gets player identifier of the given type
+---@param source any
+---@param idtype string
+---@return string?
 function QBCore.Functions.GetIdentifier(source, idtype)
     local identifiers = GetPlayerIdentifiers(source)
     for _, identifier in pairs(identifiers) do
@@ -24,6 +31,9 @@ function QBCore.Functions.GetIdentifier(source, idtype)
     return nil
 end
 
+---Gets a players server id (source). Returns 0 if no player is found.
+---@param identifier string
+---@return number
 function QBCore.Functions.GetSource(identifier)
     for src, _ in pairs(QBCore.Players) do
         local idens = GetPlayerIdentifiers(src)
@@ -36,6 +46,9 @@ function QBCore.Functions.GetSource(identifier)
     return 0
 end
 
+---Get player with given server id (source)
+---@param source any
+---@return table
 function QBCore.Functions.GetPlayer(source)
     if type(source) == 'number' then
         return QBCore.Players[source]
@@ -44,6 +57,9 @@ function QBCore.Functions.GetPlayer(source)
     end
 end
 
+---Get player by citizen id
+---@param citizenid string
+---@return table|nil
 function QBCore.Functions.GetPlayerByCitizenId(citizenid)
     for src in pairs(QBCore.Players) do
         if QBCore.Players[src].PlayerData.citizenid == citizenid then
@@ -53,10 +69,16 @@ function QBCore.Functions.GetPlayerByCitizenId(citizenid)
     return nil
 end
 
+---Get offline player by citizen id
+---@param citizenid string
+---@return table|nil
 function QBCore.Functions.GetOfflinePlayerByCitizenId(citizenid)
     return QBCore.Player.GetOfflinePlayer(citizenid)
 end
 
+---Get player by phone number
+---@param number number
+---@return table|nil
 function QBCore.Functions.GetPlayerByPhone(number)
     for src in pairs(QBCore.Players) do
         if QBCore.Players[src].PlayerData.charinfo.phone == number then
@@ -66,6 +88,8 @@ function QBCore.Functions.GetPlayerByPhone(number)
     return nil
 end
 
+---Get all players. Returns the server ids of all players.
+---@return table
 function QBCore.Functions.GetPlayers()
     local sources = {}
     for k in pairs(QBCore.Players) do
@@ -74,13 +98,16 @@ function QBCore.Functions.GetPlayers()
     return sources
 end
 
--- Will return an array of QB Player class instances
--- unlike the GetPlayers() wrapper which only returns IDs
+---Will return an array of QB Player class instances
+---unlike the GetPlayers() wrapper which only returns IDs
+---@return table
 function QBCore.Functions.GetQBPlayers()
     return QBCore.Players
 end
 
---- Gets a list of all on duty players of a specified job and the number
+---Gets a list of all on duty players of a specified job and the number
+---@param job string
+---@return table, number
 function QBCore.Functions.GetPlayersOnDuty(job)
     local players = {}
     local count = 0
@@ -95,7 +122,9 @@ function QBCore.Functions.GetPlayersOnDuty(job)
     return players, count
 end
 
--- Returns only the amount of players on duty for the specified job
+---Returns only the amount of players on duty for the specified job
+---@param job any
+---@return number
 function QBCore.Functions.GetDutyCount(job)
     local count = 0
     for _, Player in pairs(QBCore.Players) do
@@ -110,13 +139,17 @@ end
 
 -- Routing buckets (Only touch if you know what you are doing)
 
--- Returns the objects related to buckets, first returned value is the player buckets, second one is entity buckets
+---Returns the objects related to buckets, first returned value is the player buckets, second one is entity buckets
+---@return table, table
 function QBCore.Functions.GetBucketObjects()
     return QBCore.Player_Buckets, QBCore.Entity_Buckets
 end
 
--- Will set the provided player id / source into the provided bucket id
-function QBCore.Functions.SetPlayerBucket(source --[[ int ]], bucket --[[ int ]])
+---Will set the provided player id / source into the provided bucket id
+---@param source any
+---@param bucket any
+---@return boolean
+function QBCore.Functions.SetPlayerBucket(source, bucket)
     if source and bucket then
         local plicense = QBCore.Functions.GetIdentifier(source, 'license')
         SetPlayerRoutingBucket(source, bucket)
@@ -127,8 +160,11 @@ function QBCore.Functions.SetPlayerBucket(source --[[ int ]], bucket --[[ int ]]
     end
 end
 
--- Will set any entity into the provided bucket, for example peds / vehicles / props / etc.
-function QBCore.Functions.SetEntityBucket(entity --[[ int ]], bucket --[[ int ]])
+---Will set any entity into the provided bucket, for example peds / vehicles / props / etc.
+---@param entity number
+---@param bucket number
+---@return boolean
+function QBCore.Functions.SetEntityBucket(entity, bucket)
     if entity and bucket then
         SetEntityRoutingBucket(entity, bucket)
         QBCore.Entity_Buckets[entity] = {id = entity, bucket = bucket}
@@ -138,8 +174,10 @@ function QBCore.Functions.SetEntityBucket(entity --[[ int ]], bucket --[[ int ]]
     end
 end
 
--- Will return an array of all the player ids inside the current bucket
-function QBCore.Functions.GetPlayersInBucket(bucket --[[ int ]])
+---Will return an array of all the player ids inside the current bucket
+---@param bucket number
+---@return table|boolean
+function QBCore.Functions.GetPlayersInBucket(bucket)
     local curr_bucket_pool = {}
     if QBCore.Player_Buckets and next(QBCore.Player_Buckets) then
         for _, v in pairs(QBCore.Player_Buckets) do
@@ -153,8 +191,11 @@ function QBCore.Functions.GetPlayersInBucket(bucket --[[ int ]])
     end
 end
 
--- Will return an array of all the entities inside the current bucket (not for player entities, use GetPlayersInBucket for that)
-function QBCore.Functions.GetEntitiesInBucket(bucket --[[ int ]])
+---Will return an array of all the entities inside the current bucket
+---(not for player entities, use GetPlayersInBucket for that)
+---@param bucket number
+---@return table|boolean
+function QBCore.Functions.GetEntitiesInBucket(bucket)
     local curr_bucket_pool = {}
     if QBCore.Entity_Buckets and next(QBCore.Entity_Buckets) then
         for _, v in pairs(QBCore.Entity_Buckets) do
@@ -168,8 +209,13 @@ function QBCore.Functions.GetEntitiesInBucket(bucket --[[ int ]])
     end
 end
 
--- Server side vehicle creation with optional callback
--- the CreateVehicle RPC still uses the client for creation so players must be near
+---Server side vehicle creation with optional callback
+---the CreateVehicle RPC still uses the client for creation so players must be near
+---@param source any
+---@param model any
+---@param coords vector
+---@param warp boolean
+---@return number
 function QBCore.Functions.SpawnVehicle(source, model, coords, warp)
     local ped = GetPlayerPed(source)
     model = type(model) == 'string' and joaat(model) or model
@@ -186,9 +232,15 @@ function QBCore.Functions.SpawnVehicle(source, model, coords, warp)
     return veh
 end
 
--- Server side vehicle creation with optional callback
--- the CreateAutomobile native is still experimental but doesn't use client for creation
--- doesn't work for all vehicles!
+---Server side vehicle creation with optional callback
+---the CreateAutomobile native is still experimental but doesn't use client for creation
+---doesn't work for all vehicles!
+---comment
+---@param source any
+---@param model any
+---@param coords vector
+---@param warp boolean
+---@return number
 function QBCore.Functions.CreateVehicle(source, model, coords, warp)
     model = type(model) == 'string' and joaat(model) or model
     if not coords then coords = GetEntityCoords(GetPlayerPed(source)) end
@@ -199,7 +251,7 @@ function QBCore.Functions.CreateVehicle(source, model, coords, warp)
     return veh
 end
 
--- Paychecks (standalone - don't touch)
+---Paychecks (standalone - don't touch)
 function PaycheckInterval()
     if next(QBCore.Players) then
         for _, Player in pairs(QBCore.Players) do
@@ -234,17 +286,28 @@ end
 
 -- Callback Functions --
 
--- Client Callback
+---Trigger Client Callback
+---@param name string
+---@param source any
+---@param cb function
+---@param ... any
 function QBCore.Functions.TriggerClientCallback(name, source, cb, ...)
     QBCore.ClientCallbacks[name] = cb
     TriggerClientEvent('QBCore:Client:TriggerClientCallback', source, name, ...)
 end
 
--- Server Callback
+---Create Server Callback
+---@param name string
+---@param cb function
 function QBCore.Functions.CreateCallback(name, cb)
     QBCore.ServerCallbacks[name] = cb
 end
 
+---Trigger Serv er Callback
+---@param name string
+---@param source any
+---@param cb function
+---@param ... any
 function QBCore.Functions.TriggerCallback(name, source, cb, ...)
     if not QBCore.ServerCallbacks[name] then return end
     QBCore.ServerCallbacks[name](source, cb, ...)
@@ -252,21 +315,33 @@ end
 
 -- Items
 
+---Create a usable item
+---@param item string
+---@param data function
 function QBCore.Functions.CreateUseableItem(item, data)
     QBCore.UsableItems[item] = data
 end
 
+---Checks if the given item is usable
+---@param item string
+---@return any
 function QBCore.Functions.CanUseItem(item)
     return QBCore.UsableItems[item]
 end
 
+---Use item
+---@param source any
+---@param item string
 function QBCore.Functions.UseItem(source, item)
     if GetResourceState('qb-inventory') == 'missing' then return end
     exports['qb-inventory']:UseItem(source, item)
 end
 
--- Kick Player
-
+---Kick Player
+---@param source any
+---@param reason string
+---@param setKickReason boolean
+---@param deferrals boolean
 function QBCore.Functions.Kick(source, reason, setKickReason, deferrals)
     reason = '\n' .. reason .. '\n🔸 Check our Discord for further information: ' .. QBCore.Config.Server.Discord
     if setKickReason then
@@ -297,8 +372,9 @@ function QBCore.Functions.Kick(source, reason, setKickReason, deferrals)
     end)
 end
 
--- Check if player is whitelisted, kept like this for backwards compatibility or future plans
-
+---Check if player is whitelisted, kept like this for backwards compatibility or future plans
+---@param source any
+---@return boolean
 function QBCore.Functions.IsWhitelisted(source)
     if not QBCore.Config.Server.Whitelist then return true end
     if QBCore.Functions.HasPermission(source, QBCore.Config.Server.WhitelistPermission) then return true end
@@ -307,6 +383,9 @@ end
 
 -- Setting & Removing Permissions
 
+---Add permission for player
+---@param source any
+---@param permission string
 function QBCore.Functions.AddPermission(source, permission)
     if not IsPlayerAceAllowed(source, permission) then
         ExecuteCommand(('add_principal player.%s qbcore.%s'):format(source, permission))
@@ -314,6 +393,9 @@ function QBCore.Functions.AddPermission(source, permission)
     end
 end
 
+---Remove permission from player
+---@param source any
+---@param permission string
 function QBCore.Functions.RemovePermission(source, permission)
     if permission then
         if IsPlayerAceAllowed(source, permission) then
@@ -332,6 +414,10 @@ end
 
 -- Checking for Permission Level
 
+---Check if player has permission
+---@param source any
+---@param permission string
+---@return boolean
 function QBCore.Functions.HasPermission(source, permission)
     if type(permission) == "string" then
         if IsPlayerAceAllowed(source, permission) then return true end
@@ -344,6 +430,9 @@ function QBCore.Functions.HasPermission(source, permission)
     return false
 end
 
+---Get the players permissions
+---@param source any
+---@return table
 function QBCore.Functions.GetPermission(source)
     local src = source
     local perms = {}
@@ -355,8 +444,9 @@ function QBCore.Functions.GetPermission(source)
     return perms
 end
 
--- Opt in or out of admin reports
-
+---Get admin messages opt-in state for player
+---@param source any
+---@return boolean
 function QBCore.Functions.IsOptin(source)
     local license = QBCore.Functions.GetIdentifier(source, 'license')
     if not license or not QBCore.Functions.HasPermission(source, 'admin') then return false end
@@ -364,6 +454,8 @@ function QBCore.Functions.IsOptin(source)
     return Player.PlayerData.optin
 end
 
+---Toggle opt-in to admin messages
+---@param source any
 function QBCore.Functions.ToggleOptin(source)
     local license = QBCore.Functions.GetIdentifier(source, 'license')
     if not license or not QBCore.Functions.HasPermission(source, 'admin') then return end
@@ -372,8 +464,9 @@ function QBCore.Functions.ToggleOptin(source)
     Player.Functions.SetPlayerData('optin', Player.PlayerData.optin)
 end
 
--- Check if player is banned
-
+---Check if player is banned
+---@param source any
+---@return boolean, string?
 function QBCore.Functions.IsPlayerBanned(source)
     local plicense = QBCore.Functions.GetIdentifier(source, 'license')
     local result = MySQL.single.await('SELECT * FROM bans WHERE license = ?', { plicense })
@@ -387,8 +480,9 @@ function QBCore.Functions.IsPlayerBanned(source)
     return false
 end
 
--- Check for duplicate license
-
+---Check for duplicate license
+---@param license any
+---@return boolean
 function QBCore.Functions.IsLicenseInUse(license)
     local players = GetPlayers()
     for _, player in pairs(players) do
@@ -406,17 +500,31 @@ end
 
 -- Utility functions
 
+---Check if a player has an item [deprecated]
+---@param source any
+---@param items table|string
+---@param amount number
+---@return boolean
 function QBCore.Functions.HasItem(source, items, amount)
     if GetResourceState('qb-inventory') == 'missing' then return end
     return exports['qb-inventory']:HasItem(source, items, amount)
 end
 
+---Notify
+---@param source any
+---@param text string
+---@param type string
+---@param length number
 function QBCore.Functions.Notify(source, text, type, length)
     TriggerClientEvent('QBCore:Notify', source, text, type, length)
 end
 
---- SQL Pattern Matching
-function QBCore.Functions.PrepForSQL(source,data,pattern)
+---???? ... ok
+---@param source any
+---@param data any
+---@param pattern any
+---@return boolean
+function QBCore.Functions.PrepForSQL(source, data, pattern)
     data = tostring(data)
     local src = source
     local player = QBCore.Functions.GetPlayer(src)