@return - Return Value Definition

---@return <type> [variable_name] [description]

-- With comment separator
---@return <type> [variable_name] # description

-- Multiple return values
---@return <type1> [name1] [description1]
---@return <type2> [name2] [description2]

---@return User | nil User object, returns nil if not found
---@return string | nil Error message, returns nil if successful
function findUserById(id)
    local user = database:findUser(id)
    if user then
        return user, nil
    else
        return nil, "User not found"
    end
end

-- Usage with nil checking
local user, error = findUserById(123)
if user then
    print("Found:", user.name)  -- IDE knows user is User here
else
    print("Error:", error)       -- IDE knows error is string here
end

---@return {success: boolean, data: table[], count: number} Query result
function queryUsers(filters)
    local users = database:query("users", filters)
    return {
        success = true,
        data = users,
        count = #users
    }
end

-- Usage with autocomplete
local result = queryUsers({status = "active"})
print(result.success)  -- ✅ IDE autocompletes 'success'
print(result.data)     -- ✅ IDE autocompletes 'data'
print(result.count)    -- ✅ IDE autocompletes 'count'
print(result.invalid)  -- ⚠️ Warning: field doesn't exist

---@return fun(x: number): number Returns a multiplier function
function createMultiplier(factor)
    return function(x)
        return x * factor
    end
end

-- Usage
local double = createMultiplier(2)
local result = double(5)  -- IDE knows result is number

---@generic T
---@param value T
---@return T Copy of input value
function clone(value)
    return deepCopy(value)
end

-- Type flows through
local numbers = {1, 2, 3}
local cloned = clone(numbers)  -- IDE knows cloned is number[]

local user = {name = "John", age = 25}
local clonedUser = clone(user)  -- IDE knows clonedUser has same structure

---@return string ... All usernames
function getAllUserNames()
    return "John", "Jane", "Bob"
end

-- Capture all returns
local name1, name2, name3 = getAllUserNames()
-- All are known to be strings

---@param includeDetails boolean Whether to include detailed information
---@return string name Username
---@return number age Age
---@return string? email Email (only returned when includeDetails is true)
function getUserInfo(includeDetails)
    local name, age = "John", 25
    if includeDetails then
        return name, age, "[email protected]"
    else
        return name, age
    end
end

-- Usage
local name, age = getUserInfo(false)
local name2, age2, email = getUserInfo(true)
-- IDE knows email might be nil

---@return boolean success Whether operation succeeded
---@return any result Result data on success
---@return string? error Error message on failure
function safeOperation(data)
    local success, result = pcall(function()
        return processData(data)
    end)
    
    if success then
        return true, result, nil
    else
        return false, nil, result  -- result is error message
    end
end

-- Usage
local ok, data, err = safeOperation(inputData)
if ok then
    print("Success:", data)
else
    print("Error:", err)
end

---@return table | nil result Operation result
---@return string | nil error Error message if failed
function performAction()
    if someCondition then
        return {status = "complete"}, nil
    else
        return nil, "Action failed"
    end
end

---@return fun(): number?, string? Iterator function
function iterateUsers()
    local users = {"John", "Jane", "Bob"}
    local index = 0
    
    return function()
        index = index + 1
        if index <= #users then
            return index, users[index]
        end
        return nil, nil
    end
end

-- Usage in for loop
for id, userName in iterateUsers() do
    -- IDE knows id is number and userName is string
    print(id, userName)
end

---@async
---@return Promise<string> Promise of async operation
function fetchUserDataAsync(userId)
    return Promise.new(function(resolve, reject)
        setTimeout(function()
            if userId > 0 then
                resolve("User data")
            else
                reject("Invalid user ID")
            end
        end, 1000)
    end)
end

---@class User
---@field id number
---@field name string
---@field email string
---@field age number

---@class QueryResult
---@field success boolean
---@field data User[]
---@field count number
---@field page number
---@field totalPages number

---@param filters {status?: string, minAge?: number, maxAge?: number}
---@param page? number Page number (default: 1)
---@param pageSize? number Items per page (default: 10)
---@return QueryResult | nil result Query result object
---@return string | nil error Error message if query failed
function queryUsers(filters, page, pageSize)
    page = page or 1
    pageSize = pageSize or 10
    
    local success, users = pcall(function()
        return database:query("users", filters, page, pageSize)
    end)
    
    if not success then
        return nil, "Database query failed: " .. tostring(users)
    end
    
    if not users or #users == 0 then
        return nil, "No users found matching criteria"
    end
    
    local totalCount = database:count("users", filters)
    local totalPages = math.ceil(totalCount / pageSize)
    
    return {
        success = true,
        data = users,
        count = #users,
        page = page,
        totalPages = totalPages
    }, nil
end

-- Usage with full type information
local result, err = queryUsers(
    {status = "active", minAge = 18},
    1,
    20
)

if result then
    -- IDE provides autocomplete for all fields
    print("Found", result.count, "users on page", result.page)
    print("Total pages:", result.totalPages)
    
    for _, user in ipairs(result.data) do
        -- IDE knows user is User with all fields
        print(user.id, user.name, user.email, user.age)
    end
else
    -- IDE knows err is string here
    print("Query failed:", err)
end