如何在Roblox Studio中为Lua函数添加规范文档字符串？

Roblox Studio使用的是Luau（Lua的增强版），它有一套专门的文档注释语法，只有遵循这套规范，代码提示弹窗才会显示符合预期的样式。以下是正确的实现方法：

核心规则 #

• 文档注释必须以**三个减号 ---**开头（单行或多行），普通的--或--[[ ... ]]不会被识别为文档注释
• 使用@开头的标签定义函数元数据，常用标签包括@param、@return、@desc（第一行注释默认作为描述，可省略@desc）

完整示例 #

基础函数文档 #

--- 计算两个数字的加法结果
--- @param a number 第一个加数
--- @param b number 第二个加数
--- @return number 两个数的和
function add(a, b)
    return a + b
end

当你在Roblox Studio中hover这个add函数时，代码提示弹窗会规范显示描述、参数说明和返回值信息。

带可选参数的函数文档 #

--- 生成个性化问候语
--- @param name string 问候对象的名字
--- @param honorific string? 可选的头衔（如"Mr."/"Ms."）
--- @return string 格式化后的问候语句
function generateGreeting(name, honorific)
    local title = honorific and honorific .. " " or ""
    return string.format("Hello, %s%s!", title, name)
end

这里的string?表示该参数是可选的，代码提示会自动标注这一点。

常见错误排查 #

1. 错误使用双减号：之前尝试的-- @param是普通注释，必须改成--- @param才会被Luau解析器识别
2. 不规范的块注释：--//或普通--[[ ... ]]块注释无法触发文档提示，如需块注释形式，应该用--[=[包裹，内部每行仍以---开头：

--[=[
--- 批量计算数字列表的总和
--- @param numbers {number} 待求和的数字数组
--- @return number 数组元素的总和
]=]
function sumList(numbers)
    local total = 0
    for _, num in ipairs(numbers) do
        total += num
    end
    return total
end

内容的提问来源于stack exchange，提问作者Dennis Geisler