【工具链】LDoc 文档生成：Lua 注释即团队手册

实战应用：用在哪里

模块多了之后，"这个函数谁写的、参数什么含义、返回什么"只能翻源码猜。LDoc 从 Lua 注释直接生成 HTML API 手册，适用于：引擎封装层（SL/GUI 包装函数）、业务公共库（背包、邮件）、GM 命令表。文档跟着代码走 review、进版本库，新人上手时间实测从三天缩到半天。

注释格式：三横线块

LDoc 识别以三个连字符开头的注释块，紧贴函数定义：

--- 给玩家发放物品
-- 支持叠加物自动合并，背包满时返回失败
-- @string playerId 玩家唯一标识
-- number itemId 物品配置 id
-- number count 数量，默认 1
-- treturn boolean 是否全部入包
-- usage giveItem("p_10001", 1001, 5)
function giveItem(playerId, itemId, count)
    ...
end

@string/@number 声明参数类型，@treturn 声明返回值，@usage 给出可复制示例。这三类标注覆盖团队文档 90% 的需求，其余 tag（@see、@within）按需补。

生成与发布

一条命令生成整站手册：

ldoc -d docs/api -t "996 Lua 手册" -f markdown ./business

生成结果按目录分模块，函数签名、参数表、示例齐全。两个工程化接法：把 ldoc 命令挂进构建流水线，每次出包同步更新 docs 目录，手册与代码版本严格对齐；CI 里加一条检查——公共函数缺少注释块时警告，防止文档烂尾。

三条写作纪律

第一，注释写"契约"不写"实现"。 参数范围、副作用、失败时的行为才是调用方需要的；函数内部怎么实现的留给源码本身。第二，示例必须可运行。 @usage 里的代码进 busted 测试目录做冒烟验证，文档里贴一段跑不通的代码比没有文档更有害。第三，废弃标注。 函数下线前先打 @deprecated 建议改用 xxx，保留一个版本的过渡期，配合 grep 统计调用点清零后再删除。这套流程搭好后，引擎接口手册（可对照 mirs.cn 接口站的结构）与业务手册统一由 CI 产出，文档覆盖率成为可度量的工程指标。

本文由 996 技术组基于 996 引擎官方知识库与浮生梦老师课程体系整理。团队长期从事传奇类引擎 Lua 后端逻辑、客户端界面与商业版本交付，内容以官方知识库与真实项目为出处，按版本持续修订。