refactor(server): more annotations, minor refactor, and printing with…

…in deprecated functions

client/events.lua

@@ -160,7 +160,7 @@ RegisterNetEvent('QBCore:NotifyV2', function(props)
     QBCore.Functions.NotifyV2(props)
 end)
 
----@deprecated. Use event 'QBCore:NotifyV2' instead.
+---@deprecated Use event 'QBCore:NotifyV2' instead.
 ---@see client/functions.lua:QBCore.Functions.Notify
 RegisterNetEvent('QBCore:Notify', function(text, notifyType, duration)
     QBCore.Functions.Notify(text, notifyType, duration)
@@ -171,6 +171,7 @@ end)
 -- Client Callback
 ---@deprecated call a function instead
 RegisterNetEvent('QBCore:Client:TriggerClientCallback', function(name, ...)
+    print(string.format("%s invoked deprecated event QBCore:Client:TriggerClientCallback. Call a function instead", GetInvokingResource()))
     QBCore.Functions.TriggerClientCallback(name, function(...)
         TriggerServerEvent('QBCore:Server:TriggerClientCallback', name, ...)
     end, ...)
@@ -179,6 +180,7 @@ end)
 -- Server Callback
 ---@deprecated use https://overextended.github.io/docs/ox_lib/Callback/Lua/Client/ instead
 RegisterNetEvent('QBCore:Client:TriggerCallback', function(name, ...)
+    print(string.format("%s invoked deprecated event QBCore:Client:TriggerCallback. Use ox_lib callback functions instead.", GetInvokingResource()))
     if QBCore.ServerCallbacks[name] then
         QBCore.ServerCallbacks[name](...)
         QBCore.ServerCallbacks[name] = nil

client/functions.lua

@@ -140,18 +140,21 @@ end
 -- Client Callback
 ---@deprecated use https://overextended.github.io/docs/ox_lib/Callback/Lua/Client/ instead
 function QBCore.Functions.CreateClientCallback(name, cb)
+    print(string.format("%s invoked deprecated function CreateClientCallback. Use ox_lib callback functions instead.", GetInvokingResource()))
     QBCore.ClientCallbacks[name] = cb
 end
 
 ---@deprecated call a function instead
 function QBCore.Functions.TriggerClientCallback(name, cb, ...)
+    print(string.format("%s invoked deprecated function TriggerClientCallback. Use ox_lib callback functions instead.", GetInvokingResource()))
     if not QBCore.ClientCallbacks[name] then return end
     QBCore.ClientCallbacks[name](cb, ...)
 end
 
 -- Server Callback
 ---@deprecated use https://overextended.github.io/docs/ox_lib/Callback/Lua/Client/ instead
 function QBCore.Functions.TriggerCallback(name, cb, ...)
+    print(string.format("%s invoked deprecated function TriggerCallback. Use ox_lib callback functions instead.", GetInvokingResource()))
     QBCore.ServerCallbacks[name] = cb
     TriggerServerEvent('QBCore:Server:TriggerCallback', name, ...)
 end

server/events.lua

@@ -160,6 +160,7 @@ end)
 -- Client Callback
 ---@deprecated use https://overextended.github.io/docs/ox_lib/Callback/Lua/Server instead
 RegisterNetEvent('QBCore:Server:TriggerClientCallback', function(name, ...)
+    print(string.format("%s invoked deprecated event QBCore:Server:TriggerClientCallback. Use ox_lib callback functions instead.", GetInvokingResource()))
     if QBCore.ClientCallbacks[name] then
         QBCore.ClientCallbacks[name](...)
         QBCore.ClientCallbacks[name] = nil
@@ -169,6 +170,7 @@ end)
 -- Server Callback
 ---@deprecated use https://overextended.github.io/docs/ox_lib/Callback/Lua/Server instead
 RegisterNetEvent('QBCore:Server:TriggerCallback', function(name, ...)
+    print(string.format("%s invoked deprecated event QBCore:Server:TriggerCallback. Use ox_lib callback functions instead.", GetInvokingResource()))
     local src = source
     QBCore.Functions.TriggerCallback(name, src, function(...)
         TriggerClientEvent('QBCore:Client:TriggerCallback', src, name, ...)

server/exports.lua

@@ -1,4 +1,8 @@
 -- Add or change (a) method(s) in the QBCore.Functions table
+---@param methodName string
+---@param handler function
+---@return boolean success
+---@return string message
 local function SetMethod(methodName, handler)
     if type(methodName) ~= "string" then
         return false, "invalid_method_name"
@@ -15,6 +19,10 @@ QBCore.Functions.SetMethod = SetMethod
 exports("SetMethod", SetMethod)
 
 -- Add or change (a) field(s) in the QBCore table
+---@param fieldName string
+---@param data any
+---@return boolean success
+---@return string message
 local function SetField(fieldName, data)
     if type(fieldName) ~= "string" then
         return false, "invalid_field_name"
@@ -31,6 +39,10 @@ QBCore.Functions.SetField = SetField
 exports("SetField", SetField)
 
 -- Single add job function which should only be used if you planning on adding a single job
+---@param jobName string
+---@param job Job
+---@return boolean success
+---@return string message
 local function AddJob(jobName, job)
     if type(jobName) ~= "string" then
         return false, "invalid_job_name"
@@ -51,39 +63,36 @@ QBCore.Functions.AddJob = AddJob
 exports('AddJob', AddJob)
 
 -- Multiple Add Jobs
+---@param jobs table<string, Job>
+---@return boolean success
+---@return string message
+---@return Job? errorJob job causing the error message. Only present if success is false.
 local function AddJobs(jobs)
-    local shouldContinue = true
-    local message = "success"
-    local errorItem = nil
 
     for key, value in pairs(jobs) do
         if type(key) ~= "string" then
-            message = 'invalid_job_name'
-            shouldContinue = false
-            errorItem = jobs[key]
-            break
+            return false, 'invalid_job_name', jobs[key]
         end
 
         if QBCore.Shared.Jobs[key] then
-            message = 'job_exists'
-            shouldContinue = false
-            errorItem = jobs[key]
-            break
+            return false, 'job_exists', jobs[key]
         end
 
         QBCore.Shared.Jobs[key] = value
     end
 
-    if not shouldContinue then return false, message, errorItem end
     TriggerClientEvent('QBCore:Client:OnSharedUpdateMultiple', -1, 'Jobs', jobs)
     TriggerEvent('QBCore:Server:UpdateObject')
-    return true, message, nil
+    return true, 'success'
 end
 
 QBCore.Functions.AddJobs = AddJobs
 exports('AddJobs', AddJobs)
 
 -- Single Remove Job
+---@param jobName string
+---@return boolean success
+---@return string message
 local function RemoveJob(jobName)
     if type(jobName) ~= "string" then
         return false, "invalid_job_name"
@@ -104,6 +113,10 @@ QBCore.Functions.RemoveJob = RemoveJob
 exports('RemoveJob', RemoveJob)
 
 -- Single Update Job
+---@param jobName string
+---@param job Job
+---@return boolean success
+---@return string message
 local function UpdateJob(jobName, job)
     if type(jobName) ~= "string" then
         return false, "invalid_job_name"
@@ -124,7 +137,9 @@ QBCore.Functions.UpdateJob = UpdateJob
 exports('UpdateJob', UpdateJob)
 
 -- Single add item
+---@deprecated incompatible with ox_inventory. Update ox_inventory item config instead.
 local function AddItem(itemName, item)
+    print(string.format("%s invoked deprecated function AddItem. This is incompatible with ox_inventory", GetInvokingResource()))
     if type(itemName) ~= "string" then
         return false, "invalid_item_name"
     end
@@ -144,7 +159,9 @@ QBCore.Functions.AddItem = AddItem
 exports('AddItem', AddItem)
 
 -- Single update item
+---@deprecated incompatible with ox_inventory. Update ox_inventory item config instead.
 local function UpdateItem(itemName, item)
+    print(string.format("%s invoked deprecated function UpdateItem. This is incompatible with ox_inventory", GetInvokingResource()))
     if type(itemName) ~= "string" then
         return false, "invalid_item_name"
     end
@@ -161,7 +178,9 @@ QBCore.Functions.UpdateItem = UpdateItem
 exports('UpdateItem', UpdateItem)
 
 -- Multiple Add Items
+---@deprecated incompatible with ox_inventory. Update ox_inventory item config instead.
 local function AddItems(items)
+    print(string.format("%s invoked deprecated function AddItems. This is incompatible with ox_inventory", GetInvokingResource()))
     local shouldContinue = true
     local message = "success"
     local errorItem = nil
@@ -194,7 +213,9 @@ QBCore.Functions.AddItems = AddItems
 exports('AddItems', AddItems)
 
 -- Single Remove Item
+---@deprecated incompatible with ox_inventory. Update ox_inventory item config instead.
 local function RemoveItem(itemName)
+    print(string.format("%s invoked deprecated function RemoveItem. This is incompatible with ox_inventory", GetInvokingResource()))
     if type(itemName) ~= "string" then
         return false, "invalid_item_name"
     end
@@ -214,6 +235,10 @@ QBCore.Functions.RemoveItem = RemoveItem
 exports('RemoveItem', RemoveItem)
 
 -- Single Add Gang
+---@param gangName string
+---@param gang Gang
+---@return boolean success
+---@return string message
 local function AddGang(gangName, gang)
     if type(gangName) ~= "string" then
         return false, "invalid_gang_name"
@@ -234,39 +259,35 @@ QBCore.Functions.AddGang = AddGang
 exports('AddGang', AddGang)
 
 -- Multiple Add Gangs
+---@param gangs table<string, Gang>
+---@return boolean success
+---@return string message
+---@return Gang? errorGang present if success is false. Gang that caused the error message.
 local function AddGangs(gangs)
-    local shouldContinue = true
-    local message = "success"
-    local errorItem = nil
-
     for key, value in pairs(gangs) do
         if type(key) ~= "string" then
-            message = "invalid_gang_name"
-            shouldContinue = false
-            errorItem = gangs[key]
-            break
+            return false, 'invalid_gang_name', gangs[key]
         end
 
         if QBCore.Shared.Gangs[key] then
-            message = "gang_exists"
-            shouldContinue = false
-            errorItem = gangs[key]
-            break
+            return false, 'gang_exists', gangs[key]
         end
 
         QBCore.Shared.Gangs[key] = value
     end
 
-    if not shouldContinue then return false, message, errorItem end
     TriggerClientEvent('QBCore:Client:OnSharedUpdateMultiple', -1, 'Gangs', gangs)
     TriggerEvent('QBCore:Server:UpdateObject')
-    return true, message, nil
+    return true, 'success'
 end
 
 QBCore.Functions.AddGangs = AddGangs
 exports('AddGangs', AddGangs)
 
 -- Single Remove Gang
+---@param gangName string
+---@return boolean success
+---@return string message
 local function RemoveGang(gangName)
     if type(gangName) ~= "string" then
         return false, "invalid_gang_name"
@@ -287,6 +308,10 @@ QBCore.Functions.RemoveGang = RemoveGang
 exports('RemoveGang', RemoveGang)
 
 -- Single Update Gang
+---@param gangName string
+---@param gang Gang
+---@return boolean success
+---@return string message
 local function UpdateGang(gangName, gang)
     if type(gangName) ~= "string" then
         return false, "invalid_gang_name"
@@ -306,6 +331,8 @@ end
 QBCore.Functions.UpdateGang = UpdateGang
 exports('UpdateGang', UpdateGang)
 
+---@param InvokingResource string
+---@return string version
 local function GetCoreVersion(InvokingResource)
     ---@diagnostic disable-next-line: missing-parameter
     local resourceVersion = GetResourceMetadata(GetCurrentResourceName(), 'version')
@@ -318,6 +345,8 @@ end
 QBCore.Functions.GetCoreVersion = GetCoreVersion
 exports('GetCoreVersion', GetCoreVersion)
 
+---@param playerId integer server id
+---@param origin string reason
 local function ExploitBan(playerId, origin)
     local name = GetPlayerName(playerId)
     CreateThread(function()

server/functions.lua

@@ -253,18 +253,21 @@ end
 -- Client Callback
 ---@deprecated use https://overextended.github.io/docs/ox_lib/Callback/Lua/Server instead
 function QBCore.Functions.TriggerClientCallback(name, source, cb, ...)
+    print(string.format("%s invoked deprecated function TriggerClientCallback. Use ox_lib callback functions instead.", GetInvokingResource()))
     QBCore.ClientCallbacks[name] = cb
     TriggerClientEvent('QBCore:Client:TriggerClientCallback', source, name, ...)
 end
 
 -- Server Callback
 ---@deprecated use https://overextended.github.io/docs/ox_lib/Callback/Lua/Server instead
 function QBCore.Functions.CreateCallback(name, cb)
+    print(string.format("%s invoked deprecated function CreateCallback. Use ox_lib callback functions instead.", GetInvokingResource()))
     QBCore.ServerCallbacks[name] = cb
 end
 
 ---@deprecated call a function instead
 function QBCore.Functions.TriggerCallback(name, source, cb, ...)
+    print(string.format("%s invoked deprecated function TriggerCallback. Use ox_lib callback functions instead.", GetInvokingResource()))
     if not QBCore.ServerCallbacks[name] then return end
     QBCore.ServerCallbacks[name](source, cb, ...)
 end

shared/gangs.lua

@@ -1,4 +1,10 @@
 QBShared = QBShared or {}
+
+---@class Gang
+---@field label string
+---@field grades table<integer, {name: string, isboss: boolean}>
+
+---@type table<string, Gang>
 QBShared.Gangs = {
 	['none'] = {
 		label = 'No Gang',

shared/items.lua

@@ -83,7 +83,7 @@ QBShared.Items = {
 	['weapon_militaryrifle']		 = {['name'] = 'weapon_militaryrifle', 		 	['label'] = 'Military Rifle',		    ['weight'] = 1000, 		['type'] = 'weapon', 	['ammotype'] = 'AMMO_RIFLE',			['image'] = 'weapon_militaryrifle.png', ['unique'] = true, 		['useable'] = true, 	['description'] = 'Weapon Militaryrifle'},
     ['weapon_tacticalrifle']		 = {['name'] = 'weapon_tacticalrifle', 		 	['label'] = 'Service Carbine',		    ['weight'] = 1000, 		['type'] = 'weapon', 	['ammotype'] = 'AMMO_RIFLE',			['image'] = 'weapon_carbinerifle.png', ['unique'] = true, 		['useable'] = true, 	['description'] = 'Weapon Tactical Rifle'},
 
-    
+
 	-- Light Machine Guns
 	['weapon_mg'] 					 = {['name'] = 'weapon_mg', 				 	['label'] = 'Machinegun', 				['weight'] = 1000, 		['type'] = 'weapon', 	['ammotype'] = 'AMMO_MG',				['image'] = 'weapon_mg.png', 			['unique'] = true, 		['useable'] = false, 	['description'] = 'An automatic gun that fires bullets in rapid succession for as long as the trigger is pressed'},
 	['weapon_combatmg'] 			 = {['name'] = 'weapon_combatmg', 		 	  	['label'] = 'Combat MG', 				['weight'] = 1000, 		['type'] = 'weapon', 	['ammotype'] = 'AMMO_MG',				['image'] = 'weapon_combatmg.png', 		['unique'] = true, 		['useable'] = false, 	['description'] = 'A combat version of an automatic gun that fires bullets in rapid succession for as long as the trigger is pressed'},
@@ -98,7 +98,7 @@ QBShared.Items = {
 	['weapon_heavysniper_mk2']		 = {['name'] = 'weapon_heavysniper_mk2', 		['label'] = 'Heavy Sniper Mk II',	    ['weight'] = 1000, 		['type'] = 'weapon', 	['ammotype'] = 'AMMO_SNIPER',			['image'] = 'weapon_heavysniper_mk2.png', ['unique'] = true, 	['useable'] = true, 	['description'] = 'Weapon Heavysniper MK2'},
 	['weapon_marksmanrifle_mk2']	 = {['name'] = 'weapon_marksmanrifle_mk2', 		['label'] = 'Marksman Rifle Mk II',	    ['weight'] = 1000, 		['type'] = 'weapon', 	['ammotype'] = 'AMMO_SNIPER',			['image'] = 'weapon_marksmanrifle_mk2.png',	['unique'] = true, 	['useable'] = true, 	['description'] = 'Weapon Marksmanrifle MK2'},
     ['weapon_precisionrifle']	     = {['name'] = 'weapon_precisionrifle', 		['label'] = 'Precision Rifle',	        ['weight'] = 1000, 		['type'] = 'weapon', 	['ammotype'] = 'AMMO_SNIPER',			['image'] = 'weapon_marksmanrifle_mk2.png',	['unique'] = true, 	['useable'] = true, 	['description'] = 'Weapon Precision Rifle'},
- 
+
 	-- Heavy Weapons
 	['weapon_rpg'] 					 = {['name'] = 'weapon_rpg', 			      	['label'] = 'RPG', 						['weight'] = 1000, 		['type'] = 'weapon', 	['ammotype'] = 'AMMO_RPG',				['image'] = 'weapon_rpg.png', 			['unique'] = true, 		['useable'] = false, 	['description'] = 'A rocket-propelled grenade launcher'},
 	['weapon_grenadelauncher'] 		 = {['name'] = 'weapon_grenadelauncher', 	  	['label'] = 'Grenade Launcher', 		['weight'] = 1000, 		['type'] = 'weapon', 	['ammotype'] = 'AMMO_GRENADELAUNCHER',	['image'] = 'weapon_grenadelauncher.png', ['unique'] = true, 	['useable'] = false, 	['description'] = 'A weapon that fires a specially-designed large-caliber projectile, often with an explosive, smoke or gas warhead'},

shared/jobs.lua

@@ -1,5 +1,14 @@
 QBShared = QBShared or {}
 QBShared.ForceJobDefaultDutyAtLogin = true -- true: Force duty state to jobdefaultDuty | false: set duty state from database last saved
+
+---@class Job
+---@field label string
+---@field type? string
+---@field defaultDuty boolean
+---@field offDutyPay boolean
+---@field grades table<integer, {name: string, payment: number, isboss: boolean}>
+
+---@type table<string, Job>
 QBShared.Jobs = {
 	['unemployed'] = {
 		label = 'Civilian',