@deprecated - Deprecation Marker

---@deprecated [alternative_explanation]

---@deprecated
function oldFunction()
    print("This is an old function")
end

---@deprecated Please use newCalculateSum function instead
---@param numbers number[] Array of numbers
---@return number Sum
function calculateSum(numbers)
    local sum = 0
    for _, num in ipairs(numbers) do
        sum = sum + num
    end
    return sum
end

-- New replacement function
---@param numbers number[] Array of numbers
---@return number Sum
function newCalculateSum(numbers)
    return table.reduce(numbers, function(acc, num) return acc + num end, 0)
end

---@deprecated Please use ModernUser class instead
---@class OldUser
---@field id number
---@field name string
local OldUser = {}

-- New replacement class
---@class ModernUser
---@field id number
---@field name string
---@field email string
---@field createdAt string
local ModernUser = {}

---@class APIResponse
---@field success boolean
---@field data any
---@field message string
---@deprecated Please use errorMessage field instead
---@field error string

---@class FileManager
local FileManager = {}

---@deprecated Use readFileSync or readFileAsync instead
---@param path string File path
---@return string File content
function FileManager:loadFile(path)
    local file = io.open(path, "r")
    if file then
        local content = file:read("*a")
        file:close()
        return content
    end
    return ""
end

---@param path string File path
---@return string File content
function FileManager:readFileSync(path)
    local file = io.open(path, "r")
    if not file then
        error("Could not open file: " .. path)
    end
    local content = file:read("*a")
    file:close()
    return content
end

---@deprecated Since v2.0.0, use authenticateUser instead
---@param username string Username
---@param password string Password
---@return boolean Whether login succeeded
function login(username, password)
    -- Old authentication logic
    return username == "admin" and password == "secret"
end

---@deprecated Only use for legacy compatibility, migrate to new API
---@param data table Legacy data format
---@return table Converted data
function convertLegacyData(data)
    print("WARNING: Using deprecated convertLegacyData function")
    -- Conversion logic
    return {
        id = data.old_id,
        name = data.old_name,
        type = "legacy"
    }
end

local result1 = oldFunction()  
-- Warning: Function is deprecated

local result2 = calculateSum({1, 2, 3})  
-- Warning: Please use newCalculateSum function instead

local user = OldUser.new()  
-- Warning: Please use ModernUser class instead

---@deprecated Use processDataV2 for better performance
function processData(data)
    -- Old implementation
    return processDataV2(data)  -- Forward to new version
end

function processDataV2(data)
    -- New, optimized implementation
    return optimizedProcess(data)
end

---@deprecated Will be removed in v3.0.0
function oldAPI()
    if ENABLE_LEGACY_SUPPORT then
        return legacyImplementation()
    else
        error("oldAPI has been removed. Use newAPI instead.")
    end
end