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

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

阅读量：5920 次

发布时间：2019-06-19

本文共 3023 字，大约阅读时间需要 10 分钟。

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

###介绍

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

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

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

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

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

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

###安装

LDoc唯一依赖的库是,PenLight又依赖于,这些库在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 fatherperson = {	name = "",	age = 0,	father = nil}

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

在此输入图片描述

####对exported function的注释

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


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

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


     --- 解决一个平方根问题 -- @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标签来进行用法实例

上面函数的文档样式为：

在此输入图片描述