Skip to main content
Specify version requirements for APIs, features, or compatibility constraints to document when functionality is available.

Syntax

---@version <version_spec> [description]

Version Operators

  • >= - Greater than or equal to
  • > - Greater than
  • <= - Less than or equal to
  • < - Less than
  • = - Exactly equal to
  • != - Not equal to
  • , - AND (combine multiple constraints)

Examples

Minimum Version

---@version >=1.2.0
function modernFunction()
    -- This function requires version 1.2.0 or higher
    return "Available in v1.2.0+"
end

Exact Version

---@version =1.0.0
function legacyFunction()
    -- This function only works in exactly version 1.0.0
    return "Only in v1.0.0"
end

Version Range

---@version >=1.0.0,<2.0.0
function stableAPIFunction()
    -- Works in version 1.x series only
    return "Stable API v1.x"
end

Multiple Constraints

---@version >=1.5.0,!=1.6.0,<2.0.0
function patchedFunction()
    -- Available from 1.5.0, but not 1.6.0 (buggy), until 2.0.0
    return "Available with patch"
end

Lua Version Requirements

---@version Lua>=5.3
function utf8Function()
    -- Requires Lua 5.3+ for UTF-8 support
    return utf8.len("Hello 世界")
end

---@version LuaJIT>=2.1
function jitOptimizedFunction()
    -- Optimized for LuaJIT 2.1+
    local ffi = require("ffi")
    return ffi.new("int", 42)
end

Engine Version Requirements

---@version LÖVE>=11.0
function love2dNewFeature()
    -- Requires LÖVE 11.0+ for new graphics features
    love.graphics.setColor(1, 1, 1, 1)  -- New color format
end

---@version World of Warcraft>=8.0.0
function wowAPIFunction()
    -- WoW addon API function for Battle for Azeroth+
    return C_Map.GetMapInfo(1)
end

Deprecation Tracking

---@version <2.0.0
---@deprecated Removed in v2.0.0, use newFunction instead
function oldFunction()
    return "Will be removed"
end

Feature Addition

---@version >=1.3.0 Added support for async operations
function asyncFunction()
    -- New feature added in version 1.3.0
    return coroutine.create(function() end)
end

Class Version Requirements

---@version >=2.1.0
---@class ModernClass
---@field property string Available since v2.1.0
local ModernClass = {}

---@version >=2.2.0 Enhanced with new options
---@param options table Configuration options (v2.2.0+)
function ModernClass:configure(options)
    -- Enhanced method available since v2.2.0
    self.options = options
end

API Compatibility

---@version API>=3.0 RESTful API v3.0+
---@param endpoint string API endpoint
---@return table Response data
function apiCall(endpoint)
    return http.get("/api/v3/" .. endpoint)
end

Platform Requirements

---@version Windows>=10
---@version macOS>=10.15
---@version Linux>=Ubuntu18.04
function crossPlatformFunction()
    -- Requires modern operating systems
    return os.execute("modern-command")
end

Dependency Versions

---@version socket>=3.0
---@version json>=1.2.0
function networkFunction()
    local socket = require("socket")
    local json = require("json")

    local client = socket.tcp()
    local data = json.encode({message = "hello"})
    return client:send(data)
end

Beta/Alpha Support

---@version >=2.0.0-beta.1 Experimental feature
function experimentalFunction()
    -- Available in beta versions
    return "Experimental feature"
end

---@version >=1.0.0-alpha.3,<1.0.0 Alpha testing only
function alphaFunction()
    -- Only available during alpha testing
    return "Alpha feature"
end

Security Patches

---@version >=1.4.2 Security patch required
function secureFunction()
    -- Requires security patch from v1.4.2
    return "Secure implementation"
end

Performance Improvements

---@version >=3.1.0 Optimized implementation
function optimizedFunction(data)
    -- Optimized version available since 3.1.0
    return processDataFast(data)
end

Feature Flags

---@version >=2.0.0 Requires feature flag: NEW_UI
function newUIFunction()
    -- Requires both version and feature flag
    if not featureFlags.NEW_UI then
        error("NEW_UI feature flag required")
    end
    return "New UI component"
end

Conditional Behavior

---@param input string Input data
---@return string Processed output
function adaptiveFunction(input)
    ---@version >=1.5.0
    if version.current >= "1.5.0" then
        return advancedProcess(input)
    else
        ---@version >=1.0.0,<1.5.0
        return basicProcess(input)
    end
end

Use Cases

API Evolution

Document when features were added:
---@version >=1.0.0 Initial implementation
---@version >=1.5.0 Added caching support
---@version >=2.0.0 Added async support
function evolvedFunction()
    -- Implementation evolved across versions
end

Breaking Changes

Mark incompatible versions:
---@version <2.0.0 Old signature
---@deprecated Use new signature in v2.0.0+
function oldSignature(arg1, arg2) end

---@version >=2.0.0 New signature with options table
function newSignature(options) end

Platform-Specific Features

---@version LuaJIT>=2.1
---@version JIT compiler required
function ffiOptimized()
    local ffi = require("ffi")
    -- FFI-optimized implementation
end
Always test your code against the minimum version you specify to ensure compatibility.
Use semantic versioning (MAJOR.MINOR.PATCH) for clear version constraints and better compatibility tracking.

Features

Version Constraints

Specify minimum, maximum, or exact versions

Compatibility Docs

Document platform and dependency requirements

Deprecation Tracking

Track when features are added or removed

Multi-Version Support

Support multiple version constraints

Build docs developers (and LLMs) love