Back to Top

LDoc 入门

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,它有三个字段,alphabetagamma, 可以用这种下面的方式,简化上面的声明:

--- 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') 简化,内置的简化类型有

  • string
  • number
  • int
  • bool lua ‘boolean’ type
  • func ‘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
...

在输出的文档中,将会把成员分为 fileencoding两组。