Lua生成的LDoc文档注释规范

标签

• @module 模块, 一般一个文件就是一个模块.
• @classmod 和 @module 类似, 但是用来描述 class, 用这个标签后, 生成的文档中 Module 文字会变成 Class.
• @submodule 如果一个模块的内容被分到了好几个文件中, 那么就可以再其他文件中用 submodule 来定义, 后面跟上master module的名字.
• @script 和 @module 类似, 生成的文档中 Module 文字会变成 Script.

以上几个标签都是project-level, 意味着每个文件中只能包含它们其中的一个, 否则生成时就会提示 Module already declared! 错误.

• @author (multiple), @copyright, @license, @release 这几个啥意思就不必说了吧, 值得一提的是它们必须放在project-level,如 @module 标签下.
• @function, @lfunction. 用来描述函数. @function 一般情况下不用加, 只需要给函数加上—注释就可以.@lfunction 用来表示一个局部函数, 但是ldoc默认是不会导出局部变量和函数的.
• @param @int, @string, @bool, @func, @tab, @thread 用来描述函数参数, 后面几个指定了参数类型.
• @return 函数的返回值, 函数的返回值可能有多种, 因此 @return 在一个函数中也是可以多次使用的
• @raise 这个函数可能抛出的错误
• @local 最大的作用是使得一个函数不被导出, 除非使用了(unless –all)
• @see 引用文档的其他内容, 同一模块的话直接 @see xxx, 不同模块的话需要加上模块名 @see xxmodule.xxfunc
• @usage 给出函数的用例, 可以分多行来写
• @fixme, @todo 和 @warning , 意思大家应该都懂. 但是必须在函数体内部并且以 — 开头才能生效.

以上几个标签都是描述function的一些行为的

• @table 描述一个table, 也可以不加, 只需要给table加上—注释就可以.
• @field 用来描述table中的一个字段
• @section 用来把一个模块分隔成好几块
• @type 和 @class 的作用差不多, 但不能与 @class 同时存在. 一个文件中可以有多处 @type , 会和@section 似的，把文件分隔成好多份.
• @within 用来形容函数和table, 指定它们属于哪个section, 可以指定不存在的一个section, 会自动创建一个

函数的一些高级用法

显示参数的类型

函数参数@param 是不指明具体类型的, 若想指明的话可以用 @int, @string, @bool, @func, @tab, @thread 几个标签来.

可选参数与默认值

可选参数的标记是自参数标签后紧跟 [opt] 来标识, 默认值则是 [opt=xx]. 让我们看一个官方的示例:

--- a function with typed args.
-- @string name person's name
-- @int age
-- @string[opt='gregorian'] calender optional calendar
-- @int[opt=0] offset optional offset
-- @treturn string
function one (name,age,...)
end
----> displayed as: one (name, age [, calender='gregorian' [, offset=0]])

多种返回值

一个函数不同的情况可能返回不同的值, 意义也都不一样, 那么怎么来表示呢? 答案是在 @return 后紧跟 x 来标识. 生成出来的文档是用 Or 来列出这些不同的返回值的.

config.ld 的字段说明

ldoc 运行时有一堆参数可以传递, 在终端中去做比较麻烦, 修改也不太方便. 因此我们可以创建一个config.ld 配置文件来做这个事情, ldoc . 表示在当前目前下查找 config.ld 文件, ldoc -c path/to/myconfig.ld 读取特殊的目录的配置文件. 其实 config.ld 就是一个lua文件, 填写时需要遵循lua语法.

• file 可以是一个文件名或者目录名, 如: file = ‘test.lua’. file 也可以是一个table, 这时里面可以填写文件数组或目录数组, 同时也可以包含另一个特殊的数组 exclude, 表明要排除的文件或目录
• project 项目的名称, 会出现在文档的左上角. 默认为 ldoc
• title 页面的名称, 默认为 Reference
• all 导出 local 的 function
• output 导出 html 的名字, 默认是 index
• dir 导出目录的名字, 默认是 doc
• colon 使用冒号风格代替 @ 风格的 tag
• boilerplate 忽略所有源文件中的首个注释(块), 比如: license 注释.
• ext 输出文件的后缀(默认为 html)
• one 文档使用单列的布局
• style, template 指定模板和样式的目录. 在 config.ld 中它也可以为 true , 表示使用和配置文件同一目录的模板.
• merge 允许文档从不同的文件合并同名的 module , 而不是产生多个module.

附录:

官方文档: 这里 github地址: 这里