LDoc 是lua的文档生成工具，它可以扫描lua代码或C代码，将注释导出为文档。详细了解请查阅文档。本文仅针对我们项目可能用到的内容进行入门。
配置
LDoc 提供两种配置，命令行或配置文件（默认为 config.ld ）.
文档注释
只有满足特定格式的注释才会被LDoc处理，本文称之为文档注释，三个连字符 + 说明，或者 至少三个连字符的空行
--- summary.
-- Description; this can extend over
-- several lines
-----------------
-- This will also do.也可以使用lua块注释：
--[[--
Summary. A description
...;
]]模块或者脚本的文档注释必须在文件头，否则将会输出警告，如果代码规范要求文件头有其他用途，如增加版权说明，可使用 -B 命令或者 boilerplate=true 配置忽略第一个注释块。
’—- (text) —–‘这种注释模式会被忽略，可用于程序辅助行的注释。
标签 Tag
标签以@开头，用于描述文档注释
模块标签
下面的例子标记了一个模块名为test，描述为a test module的注释文档。
--- a test module
-- @module test
local test = {}
function test.my_module_function_1()
...
end
...
return test当test和模块名不同时，会导致模块中函数识别有问题，可通过 @alias test调整。
下面的例子，如果没有第三行，文档中first function的函数名为test.my_module_function_1，
当有了第三行，则为my_module_function_1
--- a test module
-- @module newtest
-- @alias test
local test = {}
--- first function
function test.my_module_function_1()
...
end
...
return test 函数标签
--- foo explodes text.
-- It is a specialized splitting operation on a string.
-- @param text the string
-- @return a table of substrings
-- @raise file and pattern must be strings
function foo (text)
....
end - 参数标签格式：@param 参数名 参数说明
- 返回值标签格式： @return 返回值说明
- raise标签用于抛出的异常
可以使用 ‘tparam’ and ‘treturn’ 标签指定参数或返回值的类型。
-- @tparam string text this parameter is named 'text' and has the fixed type 'string'
-- @treturn {string,...} a table of substrings- 参数标签：@tparam 类型 参数名 参数说明
- 返回值标签 @treturn 类型 返回值说明
对于lua函数，ldoc会分析函数名，但可以使用tag明确的指定函数名。如下的代码，在文档中的函数名为 newfoo
--- foo explodes text.
-- It is a specialized splitting operation on a string.
-- @function newfoo
-- @param text the string
-- @return a table of substrings
function foo (text)
....
end 导出的table和字段
--- a useful table of constants
-- @field alpha first correction
-- @field beta second correction
-- @field gamma fudge factor
-- @table constants这样可以声明一个名为constants的导出table，它有三个字段，alpha，beta，gamma，
可以用这种下面的方式，简化上面的声明：
--- a useful table of constants
M.constants = {
alpha = 0.23, -- first correction
beta = 0.443, -- second correction
gamma = 0.01 -- fudge factor
}导出字段示例：
--- module version.
M._VERSION = '0.5'usage标签
示例代码标签：
---------
-- split a string in two.
-- @param s the string
-- @param delim the delimiter (default space)
-- @return first part
-- @return second part
-- @usage local hello,world = split2("hello world")
-- @see split
funtion split2(s,delim) .. end参数简化
参数标签的格式为： @tparam <type> <parmname> <comment>
可以通过 tparam_alias('string','string') 简化，内置的简化类型有
stringnumberintboollua ‘boolean’ typefunc‘function’ (using ‘function’ would conflict with the type)tab‘table’thread
例如 @tparam string name player's name 可以简化为 @string name player's name
可为空参数
可以使用opt标签
---- testing [opt]
-- @param one
-- @param[opt] two
-- @param three
-- @param[opt] four
function fun (one,two,three,four)
end
----> displayed as: fun (one [, two], three [, four])多返回值或多种返回值
可以使用多个@return表示有多个返回值，可以用@return[1]表示有多组返回值。例如
-----
-- function with return groups.
-- @return[1] result
-- @return[2] nil
-- @return[2] error message
function mul1() ... end函数返回 result 或者是 nil, errror message.
模块成员分组
通过section标签可以对函数，table进行分组。
--- File functions.
-- Useful utilities for opening foobar format files.
-- @section file
--- open a file
...
--- read a file
...
--- Encoding operations.
-- Encoding foobar output in different ways.
-- @section encoding
...在输出的文档中，将会把成员分为 file 和 encoding两组。