Lua annotations provide a powerful way to document code and enable better type checking and auto-completion in modern development environments. This guide will walk you through everything you need to know about Lua annotations, from basic concepts to advanced usage.
What Are Lua Annotations?
Lua annotations are special comments that start with three dashes (---) instead of the standard two dashes (--). These annotations provide additional information about your code that can be used by development tools for:
Type checking
Code completion
Documentation generation
Better code understanding
Basic Syntax
Lua annotations always begin with three dashes followed by an @ symbol and the annotation type:
---@type stringlocal name ="John"---@param x number The value to square---@return number The squared valuelocalfunctionsquare(x)return x * x
end
---@param name string The user's name---@param age number The user's age---@param isAdmin boolean Whether the user is an administratorlocalfunctioncreateUser(name, age, isAdmin)-- Function implementationend
Return Values (@return)
Specify function return types:
---@return boolean success Whether the operation succeeded---@return string? error Error message if operation failedlocalfunctionsaveData()-- Function implementationend
Classes and Fields
Define classes and their fields:
---@class Player---@field name string---@field health number---@field level integerlocal Player ={}function Player:new()local instance ={ name ="", health =100, level =1}returnsetmetatable(instance,{ __index = Player })end
Advanced Features
Type Aliases (@alias)
Create custom type aliases for reusability:
---@alias UserID string---@alias Status "active"|"inactive"|"banned"---@param id UserID---@param status StatuslocalfunctionupdateUserStatus(id, status)-- Function implementationend
Generic Types (@generic)
Define generic types for flexible functions:
---@generic T---@param list T[]---@return T?localfunctiongetFirstElement(list)return list[1]end
Union Types
Specify multiple possible types:
---@type string|numberlocal identifier
---@param value string|number|booleanlocalfunctionprocess(value)-- Function implementationend
Best Practices
Be Consistent
Use annotations consistently across your codebase
Follow the same format for similar functions
Provide Clear Descriptions
Add meaningful descriptions to parameters and return values
Use clear and concise language
---@param userId string The unique identifier of the user---@param options table Configuration options for the action---@return boolean success Whether the action was successful---@return string? error Error message if the action failedlocalfunctionperformAction(userId, options)-- Function implementationend
Document Nullable Types
Use ? suffix for nullable types
Be explicit about optional parameters
---@param callback? function Optional callback function---@return string? result May be nil if operation failslocalfunctiondoSomething(callback)-- Function implementationend
Organize Complex Types
Use type aliases for complex types
Break down complex structures into smaller, documented parts
---@alias Point {x: number, y: number}---@alias Size {width: number, height: number}---@alias Rectangle {position: Point, size: Size}---@param rect RectanglelocalfunctiondrawRectangle(rect)-- Function implementationend
Major IDEs and editors that support Lua annotations:
VSCode with Lua Language Server
IntelliJ IDEA with EmmyLua plugin
ZeroBrane Studio
Neovim with LSP
Tips for Documentation
Keep It Brief
---@param x number Input value-- Better than long, multi-line descriptions for simple parameters
Use Consistent Terminology
---@param callback function Called when operation completes---@param handler function Called when event occurs-- Use consistent terms for similar concepts
Document Edge Cases
---@param divisor number Must be non-zero---@return number quotient---@return string? error Returns error message if divisor is zero
Conclusion
Lua annotations are a powerful tool for improving code quality and maintainability. By providing clear type information and documentation, they help catch errors early and make code easier to understand and maintain. Start small with basic annotations and gradually incorporate more advanced features as you become comfortable with the syntax.
Remember that the goal of annotations is to make your code more maintainable and easier to understand. Use them consistently and thoughtfully, and they'll become an invaluable part of your Lua development workflow.