feat: diagnostic comments (#562)

* feat: diagnostic comments

* fix(bridge/qb/server/player): return type

* fix: RandomInt and RandomStr

* fix(bridge/qb/server/functions): set missing param instead of diagnostic

* fix(functions): HasPlayerGotGroup optional param

* fix(moduke/utils): avoid redundant return value

* fix(bridge/qb/shared/main): revert RandomInt and RandomStr changes

* fix(server/functions): remove pcall

Author: mafewtm

bridge/qb/client/main.lua

@@ -11,6 +11,8 @@ qbCoreCompat.Shared.Jobs = GetJobs()
 qbCoreCompat.Shared.Gangs = GetGangs()
 qbCoreCompat.Functions = require 'bridge.qb.client.functions'
 
+---@diagnostic disable: deprecated
+
 ---@deprecated use https://overextended.github.io/docs/ox_lib/Callback/Lua/Client/ instead
 qbCoreCompat.ClientCallbacks = {}
 

bridge/qb/server/functions.lua

@@ -37,7 +37,7 @@ function functions.SpawnVehicle(source, model, coords, warp)
     local veh = CreateVehicle(model, coords.x, coords.y, coords.z, heading, true, true)
     while not DoesEntityExist(veh) do Wait(0) end
     if warp then
-        while GetVehiclePedIsIn(ped) ~= veh do
+        while GetVehiclePedIsIn(ped, false) ~= veh do
             Wait(0)
             TaskWarpPedIntoVehicle(ped, veh, -1)
         end
@@ -436,6 +436,7 @@ function functions.AddPlayerMethod(ids, methodName, handler)
         end
     elseif idType == 'table' and table.type(ids) == 'array' then
         for i = 1, #ids do
+            ---@diagnostic disable-next-line: deprecated
             functions.AddPlayerMethod(ids[i], methodName, handler)
         end
     end
@@ -457,15 +458,18 @@ function functions.AddPlayerField(ids, fieldName, data)
     if idType == 'number' then
         if ids == -1 then
             for _, v in pairs(QBX.Players) do
+                ---@diagnostic disable-next-line: undefined-field
                 v.Functions.AddField(fieldName, data)
             end
         else
             if not QBX.Players[ids] then return end
 
+            ---@diagnostic disable-next-line: undefined-field
             QBX.Players[ids].Functions.AddField(fieldName, data)
         end
     elseif idType == 'table' and table.type(ids) == 'array' then
         for i = 1, #ids do
+            ---@diagnostic disable-next-line: deprecated
             functions.AddPlayerField(ids[i], fieldName, data)
         end
     end
@@ -520,7 +524,7 @@ function functions.GetSource(identifier)
 end
 
 ---@param source Source|string source or identifier of the player
----@return Player
+---@return Player?
 function functions.GetPlayer(source)
     return AddDeprecatedFunctions(exports.qbx_core:GetPlayer(source))
 end
@@ -687,4 +691,4 @@ function functions.GetCoreVersion(InvokingResource)
     return exports.qbx_core:GetCoreVersion(InvokingResource)
 end
 
-return functions
+return functions

bridge/qb/server/main.lua

@@ -6,6 +6,7 @@ require 'bridge.qb.server.events'
 local convertItems = require 'bridge.qb.shared.compat'.convertItems
 convertItems(require '@ox_inventory.data.items', require 'shared.items')
 
+---@diagnostic disable-next-line: lowercase-global
 qbCoreCompat = {}
 
 qbCoreCompat.Config = lib.table.merge(require 'config.server', require 'config.shared')
@@ -20,6 +21,8 @@ qbCoreCompat.UsableItems = QBX.UsableItems
 qbCoreCompat.Functions = require 'bridge.qb.server.functions'
 qbCoreCompat.Commands = require 'bridge.qb.server.commands'
 
+---@diagnostic disable: deprecated
+
 ---@deprecated Call lib.print.debug() instead
 qbCoreCompat.Debug = lib.print.debug
 

bridge/qb/server/player.lua

@@ -86,9 +86,9 @@ end
 ---Will cause major issues!
 ---@param playerData PlayerData
 ---@param Offline boolean
----@return Player player
+---@return Player?
 function playerObj.CreatePlayer(playerData, Offline)
-    AddDeprecatedFunctions(exports.qbx_core:CreatePlayer(playerData, Offline))
+    return AddDeprecatedFunctions(exports.qbx_core:CreatePlayer(playerData, Offline))
 end
 
 ---Save player info to database (make sure citizenid is the primary key in your database)

bridge/qb/shared/main.lua

@@ -71,6 +71,8 @@ qbShared.StarterItems = {}
 if type(starterItems) == 'table' then
     for i = 1, #starterItems do
         local item = starterItems[i]
+
+        ---@diagnostic disable-next-line: deprecated
         qbShared.StarterItems[item.name] = {
             amount = item.amount,
             item = item.name,
@@ -85,12 +87,16 @@ qbShared.CommaValue = lib.math.groupdigits
 qbShared.RandomStr = function(length)
     if length <= 0 then return '' end
     local pattern = math.random(2) == 1 and 'a' or 'A'
+
+    ---@diagnostic disable-next-line: deprecated
     return qbShared.RandomStr(length - 1) .. lib.string.random(pattern)
 end
 
 ---@deprecated use lib.string.random from ox_lib
 qbShared.RandomInt = function(length)
     if length <= 0 then return '' end
+
+    ---@diagnostic disable-next-line: deprecated
     return qbShared.RandomInt(length - 1) .. lib.string.random('1')
 end
 

client/events.lua

@@ -21,6 +21,7 @@ RegisterNetEvent('QBCore:Client:OnPlayerUnload', function()
 end)
 
 ---@param value boolean
+---@diagnostic disable-next-line: param-type-mismatch
 AddStateBagChangeHandler('PVPEnabled', nil, function(bagName, _, value)
     if bagName == 'global' then
         SetCanAttackFriendly(cache.ped, value, false)
@@ -150,6 +151,7 @@ end)
 
 ---@param bagName string
 ---@param value string
+---@diagnostic disable-next-line: param-type-mismatch
 AddStateBagChangeHandler('me', nil, function(bagName, _, value)
     if not value then return end
 

client/main.lua

@@ -1,4 +1,6 @@
 QBX = {}
+
+ ---@diagnostic disable-next-line: missing-fields
 QBX.PlayerData = {}
 QBX.Shared = require 'shared.main'
 QBX.IsLoggedIn = false
@@ -37,6 +39,7 @@ function GetLocations()
     return QBX.Shared.Locations
 end
 
+---@diagnostic disable-next-line: deprecated
 exports('GetLocations', GetLocations)
 
 AddStateBagChangeHandler('isLoggedIn', ('player:%s'):format(cache.serverId), function(_, _, value)

modules/playerdata.lua

@@ -4,6 +4,7 @@ QBX = {} -- luacheck: ignore
 QBX.PlayerData = exports.qbx_core:GetPlayerData() or {}
 
 RegisterNetEvent('QBCore:Client:OnPlayerUnload', function()
+    ---@diagnostic disable-next-line: missing-fields
     QBX.PlayerData = {}
 end)
 

modules/utils.lua

@@ -1,3 +1,5 @@
+---@diagnostic disable: deprecated
+
 lib.print.warn('This resource is still using the deprecated qbx_core utils!')
 lib.print.warn('If you are the author, please update to use the new lib module. If you are not, please tell them to update!')
 
@@ -147,12 +149,14 @@ if isServer then
         model = type(model) == 'string' and joaat(model) or (model --[[@as integer]])
         local ped = GetPlayerPed(source)
 
-        return qbx.spawnVehicle({
+        local netId, _ = qbx.spawnVehicle({
             model = model,
             spawnSource = coords or ped,
             warp = warp and ped or nil,
             props = props,
         })
+
+        return netId
     end
 
 

server/commands.lua

@@ -66,6 +66,7 @@ lib.addCommand('addpermission', {
         return
     end
 
+    ---@diagnostic disable-next-line: deprecated
     AddPermission(player.PlayerData.source, permission)
 end)
 
@@ -84,6 +85,7 @@ lib.addCommand('removepermission', {
         return
     end
 
+    ---@diagnostic disable-next-line: deprecated
     RemovePermission(player.PlayerData.source, permission)
 end)
 

server/events.lua

@@ -212,14 +212,17 @@ local function playerStateBagCheck(bagName, meta, value)
     end)
 end
 
+ ---@diagnostic disable-next-line: param-type-mismatch
 AddStateBagChangeHandler('hunger', nil, function(bagName, _, value)
     playerStateBagCheck(bagName, 'hunger', value)
 end)
 
+ ---@diagnostic disable-next-line: param-type-mismatch
 AddStateBagChangeHandler('thirst', nil, function(bagName, _, value)
     playerStateBagCheck(bagName, 'thirst', value)
 end)
 
+ ---@diagnostic disable-next-line: param-type-mismatch
 AddStateBagChangeHandler('stress', nil, function(bagName, _, value)
     playerStateBagCheck(bagName, 'stress', value)
 end)

server/functions.lua

@@ -235,6 +235,7 @@ function AddPermission(source, permission)
 end
 
 ---@deprecated use cfg ACEs instead
+---@diagnostic disable-next-line: deprecated
 exports('AddPermission', AddPermission)
 
 ---@deprecated use cfg ACEs instead
@@ -250,6 +251,8 @@ function RemovePermission(source, permission)
         end
     else
         local hasUpdated = false
+
+        ---@diagnostic disable-next-line: deprecated
         for _, v in pairs(serverConfig.permissions) do
             if IsPlayerAceAllowed(source --[[@as string]], v) then
                 lib.removePrincipal('player.' .. source, 'group.' .. v)
@@ -265,6 +268,7 @@ function RemovePermission(source, permission)
 end
 
 ---@deprecated use cfg ACEs instead
+---@diagnostic disable-next-line: deprecated
 exports('RemovePermission', RemovePermission)
 
 -- Checking for Permission Level
@@ -285,13 +289,16 @@ function HasPermission(source, permission)
 end
 
 ---@deprecated use IsPlayerAceAllowed
+---@diagnostic disable-next-line: deprecated
 exports('HasPermission', HasPermission)
 
 ---@deprecated use cfg ACEs instead
 ---@param source Source
 ---@return table<string, boolean>
 function GetPermission(source)
     local perms = {}
+
+    ---@diagnostic disable-next-line: deprecated
     for _, v in pairs (serverConfig.permissions) do
         if IsPlayerAceAllowed(source --[[@as string]], v) then
             perms[v] = true
@@ -301,6 +308,7 @@ function GetPermission(source)
 end
 
 ---@deprecated use cfg ACEs instead
+---@diagnostic disable-next-line: deprecated
 exports('GetPermission', GetPermission)
 
 -- Opt in or out of admin reports
@@ -407,16 +415,15 @@ exports('GetCoreVersion', GetCoreVersion)
 ---@param origin string reason
 local function ExploitBan(playerId, origin)
     local name = GetPlayerName(playerId)
-    local success, errorResult = pcall(
-        storage.insertBan({
-            name = name,
-            license = GetPlayerIdentifierByType(playerId --[[@as string]], 'license2') or GetPlayerIdentifierByType(playerId --[[@as string]], 'license'),
-            discordId = GetPlayerIdentifierByType(playerId --[[@as string]], 'discord'),
-            ip = GetPlayerIdentifierByType(playerId --[[@as string]], 'ip'),
-            reason = origin,
-            expiration = 2147483647,
-            bannedBy = 'Anti Cheat'
-        }))
+    local success, errorResult = storage.insertBan({
+        name = name,
+        license = GetPlayerIdentifierByType(playerId --[[@as string]], 'license2') or GetPlayerIdentifierByType(playerId --[[@as string]], 'license'),
+        discordId = GetPlayerIdentifierByType(playerId --[[@as string]], 'discord'),
+        ip = GetPlayerIdentifierByType(playerId --[[@as string]], 'ip'),
+        reason = origin,
+        expiration = 2147483647,
+        bannedBy = 'Anti Cheat'
+    })
     if not success then lib.print.error(errorResult) end
     DropPlayer(playerId --[[@as string]], locale('info.exploit_banned', serverConfig.discord))
     logger.log({

server/main.lua

@@ -113,4 +113,5 @@ function GetLocations()
     return QBX.Shared.Locations
 end
 
-exports('GetLocations', GetLocations)
+---@diagnostic disable-next-line: deprecated
+exports('GetLocations', GetLocations)

server/player.lua

@@ -419,6 +419,7 @@ exports('RemovePlayerFromGang', removePlayerFromGang)
 ---@return Player player
 function CheckPlayerData(source, playerData)
     playerData = playerData or {}
+    ---@diagnostic disable-next-line: param-type-mismatch
     local playerState = Player(source)?.state
     local Offline = true
     if source then

shared/functions.lua

@@ -24,7 +24,7 @@
 
 ---@param filter string | string[] | table<string, number>
 ---@param playerData table
----@param primary boolean Check only for primary job/gang
+---@param primary? boolean Check only for primary job/gang
 ---@return boolean
 function HasPlayerGotGroup(filter, playerData, primary)
     local groups = not primary and GetPlayerGroups(playerData)

types.lua

@@ -1,5 +1,8 @@
 ---@meta
 
+---@alias NotificationPosition 'top' | 'top-right' | 'top-left' | 'bottom' | 'bottom-right' | 'bottom-left' | 'center-right' | 'center-left'
+---@alias NotificationType 'info' | 'warning' | 'success' | 'error'
+
 ---@class ErrorResult
 ---@field code string
 ---@field message string