Skip to content

README.md

Latest commit

 

History

History
135 lines (108 loc) · 4.52 KB

README.md

File metadata and controls

135 lines (108 loc) · 4.52 KB

EmmyLua Annotations Documentation Index

中文版

This directory contains detailed documentation and examples for all EmmyLua annotations.

Syntax Notation Symbols

The following notation symbols are used in annotation syntax descriptions:

  • <name> - Required placeholder that must be replaced with actual values
  • [value] - Optional item, content within brackets is optional
  • [value...] - Optional and repeatable item
  • value1 | value2 - Choice item, use either left or right value
  • <type[|type...]> - Type expression, supports union types
  • [(modifier)] - Optional modifier, such as (exact), (key), etc.
  • # - Comment marker, followed by description text

Core Annotations

Type System

Function Annotations

  • @param - Parameter definition
  • @return - Return value definition
  • @return_overload (see @return) - Correlated return tuples
  • @overload - Function overload
  • @async - Async function marker
  • @nodiscard - Non-discardable return value

Type Operations

Code Quality

Metadata

Other Annotations

Usage Guide

Basic Usage

Most annotations use the ---@ prefix and follow this format:

---@annotation_name parameters description

Common Combinations

-- Class definition combination
---@class User
---@field id number User ID
---@field name string Username
---@field email string Email address

-- Function definition combination
---@param name string Username
---@param age number User age
---@return User User object
function createUser(name, age)
    return {id = generateId(), name = name, age = age}
end

-- Generic function combination
---@generic T
---@param items T[] List of items
---@param predicate fun(item: T): boolean Filter condition
---@return T[] Filtered list
function filter(items, predicate)
    -- Implementation code
end

Best Practices

  1. Types First: Define types before using them
  2. Progressive Enhancement: Start with basic annotations, gradually add more complex ones
  3. Consistency: Maintain consistent annotation style throughout the project
  4. Documentation: Provide detailed descriptions for complex types and functions
  5. Test Validation: Use type checking tools to validate annotation correctness

Annotation Categories

Type Definition

  • @alias - Simplify complex types
  • @class - Define object structure
  • @enum - Define enumeration values
  • @generic - Define generic parameters

Function Related

  • @param - Parameter types and descriptions
  • @return - Return value types and descriptions
  • @overload - Multiple calling methods
  • @async - Async function marker

Code Quality

  • @deprecated - Mark obsolete code
  • @diagnostic - Control warning display
  • @nodiscard - Force return value checking

Tool Support

  • @meta - Type definition files
  • @cast - Runtime type conversion

Quick Reference

Annotation Purpose Example
@alias Type alias ---@alias StringOrNumber string | number
@class Class definition ---@class User
@field Field definition ---@field name string
@param Parameter definition ---@param name string
@return Return value definition ---@return boolean
@return_overload Correlated return tuples ---@return_overload true, T
@type Type declaration ---@type string
@generic Generic definition ---@generic T
@overload Function overload ---@overload fun(x: number): number
@deprecated Deprecation marker ---@deprecated Use new method instead
@cast Type casting ---@cast value string

For more detailed information, please refer to the specific documentation for each annotation.
⚡