【深入Lua】使用LDoc替代LuaDoc给Lua生成文档

如果你觉得本文的排版不舒服，您可以下载我的PDF文档：新浪微盘
如果您觉得本文有用，可以在微博上关注我，每周我都会在微博上发布新博客发表的通知，我的微博

介绍

LDoc是一个Lua的文档生成工具，过去，比较常用的Lua生成文档的工具是LuaDoc，可惜作者自从2008年之后就再也没有发布过新的版本了，说明作者基本上已经放弃维护了。而LDoc则是一直在更新中，所以现在选择LDoc来给Lua生成文档是更好的选择，LDoc的Github主页。

LDoc的一个优点就是，它的目的是为了和LuaDoc兼容并且拓展LuaDoc的功能而制作的，所以LuaDoc能够使用的标签LDoc也都可以使用。

LDoc还有一些其他的LuaDoc不具备的优点，比如

LDoc可以生成Markdown格式的文档.

LDoc生成的文档也也更加美观等等。

LDoc虽然可以针对某个lua文件生成文档，但是更加推荐的方式是通过config.ld来对需要生成文档的项目进行配置，之后，只要在config.ld所在的文档使用

ldoc .

即可对配置好的文件夹生成文档。

安装

LDoc唯一依赖的库是Penlight,PenLight又依赖于LuaFileSystem,这些库在LuaForWindows中都已经有了，如果你不想管这些事的话，你也可以直接通过luarocks来安装LDoc

luarocks install LDoc

使用

第一步我们需要配置一个config.ld文件来说明我们的项目，在这次演示中，我们创建了一个名字叫做testLDoc的项目，config.ld中的内容如下：

project='testLDoc'
title='一个用于测试LDoc的项目'
description='一个用于测试LDoc的项目'
file='.'

在这个文件中，file这一项的含义是需要生成文档的源文件的位置，需要是一个文件目录，当添加了这个目录之后，它的

所有子目录

默认也会被扫描,比如下图中的sub.submodule就是处于子目录下的模块，也会一并显示在文档中。

添加了项目名称后，它生成的文档样式如下：



在项目中，我们每一个lua文件可以看成是一个模块，模块的文档标注如下：

我们先给出一个Lua脚本的实例，这是一个模块的开头处需要的声明

--- 这是一个测试用的Lua模块
-- 在此处，我们添加模块描述
-- @module Person
-- @author wangxuanyi
-- @license MIT
-- @copyright NJU software Institue

这段注释代码，生成的文档样例如下：



注意到上文中的

---

了吗？这里是有深意的。

LDoc遵循JavaDoc等文档生成工具的传统，即只有

doc comment

可以被解析，这种

doc comment

必须以三个

-

开头。

如下：

--- summary.
-- Description; this can extend over
-- several lines

-----------------
-- This will also do.

在Lua中，一个module通常包括导出函数（exported functions），私有函数（local fucntions），表（tables）和变量（fields）。我们将依次讲解这四种东西怎么写出可被解析的注释。

对table的注释

如果，我们想添加一个table的时候，需要这么写注释：

---
-- 这是一个人的类，它有姓名和年龄两个属性
-- 在这个类中，我们规定了name和age的类型
-- @string name
-- @int age
-- @tparam person father
person = {
name = "",
age = 0,
father = nil
}

这段注释代码，生成的文档样例如下：

对exported function的注释

如果我们添加了一个exported function时，我们需要对这个函数进行解释，比如这种：

--- 通过这个方法可以得到该Person的父亲
-- @treturn person father
function person:getFather(  )
return self.father
end

或者这种更加复杂的导出函数：

--- 解决一个平方根问题
-- @number a first coeff
-- @number b second coeff
-- @number c third coeff
-- @return first root, or nil
-- @return second root, or imaginary root error
-- @usage local r1, r2 = solve(1, 2, 3)
function solve (a,b,c)
local disc = b^2 - 4*a*c
if disc < 0 then
return nil,"imaginary roots"
else
disc = math.sqrt(disc)
return (-b + disc)/2*a,
(-b - disc)/2*a
end
end

可以看到在这段代码中，实际上函数是有两个返回值的，我们可以对这两个返回值分别解释，并且可以通过usage标签来进行用法实例

上面函数的文档样式为：

local function和fields

如果我们添加了一个local function时，我们通常是不需要写注释的，因为这种函数是私有的不应当放在文档中。

如果想要添加fields，fields一般是常量，可以将一组相关的常量放在一个表里，这种写法和table的写法想死，就不再赘述。

类型标签

上文中有两种特殊的参数和返回值，即tparam和treturn，这两种类型都是可以自定义的，其语法如下：

tparam <typename> <comment>

比如，我需要一个Person的参数时，我就会这样声明

tparam Person need a Person

，其中Person就是typename，need a Person就是comment

LDoc中的标签

通过上述的讲解，我们发现LDoc中十分好用的一点就是可以标识某个参数的类型，那么LDoc到底支持哪些类型呢？

可以通过一个列表来说明：

string

number

int

bool

func 标识

‘function’

tab 标识

‘table’

thread 标识

’coroutine‘

另外我们还可以通过tparam和treturn来规定自定义类型，有几种类型是建议支持的：

Person 一个已知的类型（一般是一个lua的表）

{string, num} 一个已知类型的list

{Person, …} 一个Person的数组

{[string] = Person, …} 一个记录固定类型键值对的map

拓展阅读

如果你还想了解更多关于LDoc的细节，可以访问作者的官方文档:LDoc