使用Ldoc给Lua生成文档

Ldoc介绍

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

　　LDoc的一个优点就是，它的目的是为了和LuaDoc兼容并且拓展LuaDoc的功能而制作的，所以LuaDoc能够使用的标签LDoc也都可以使用。LDoc还有一些其他的LuaDoc不具备的优点，比如

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

LDoc生成的文档也也更加美观等等。
其逻辑是由lua代码编写，方便自己修改和理解源码

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

Ldoc安装

　　Ldoc唯一依赖的库是Penlight,PenLight又依赖于LuaFileSystem,这些库在LuaForWindows中都已经有了。可以直接通过luarocks来安装LDoc:

luarocks install Ldoc -v

　　而luarocks可以参见D.H.Q的烂笔头的这篇文章Lua 的模块安装和部署工具 - LuaRocks；讲的很详细，也可以接触更多关于LuaRocks的功能。在Mac下面安装luarocks 可以直接使用brew来安装(当然也有可能不会成功，如果Brew没有内置luarocks的话)：

brew install luarocks -v

　　最好还是安装luarocks官网上的办法(Installing LuaRocks in a Unix system:)：

wget http://luarocks.org/releases/luarocks-2.2.1.tar.gz

tar zxpf luarocks-2.2.1.tar.gz

cd luarocks-2.2.1

./configure; sudo make bootstrap

sudo luarocks install luasocket

wget，Mac下是没有自带的，可以使用brew来安装；brew也是没有自带的，其安装可以参见Here；

Ldoc使用

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

project='testLDoc'

title='一个用于测试LDoc的项目'

description='一个用于测试LDoc的项目'

file='.'

　　在这个文件中，file这一项的含义是需要生成文档的源文件的位置，需要是一个文件目录，当添加了这个目录之后，它的所有子目录默认也会被扫描,比如下图中的sub.submodule就是处于子目录下的模块，也会一并显示在文档中。添加了项目名称后，它生成的文档样式如下：

　　简单使用，安装配置完毕直接: ldoc -v xxx目录 即可在config.ld同目录下生成doc文件夹，内部有index.html,打开即可看到生成的文档。

　　对于写好注释的Table，Function，以及Exported Function等等，Ldoc都能进行完好的解析。并且生成格式美观的文档。具体效果可参见[Here](exported function)。即便是类似如下比较复杂的函数，ldoc也可以进行完好的解析。

 --- 解决一个平方根问题

 -- @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标签来进行用法实例。上面函数的文档样式为：

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

原文首贴链接http://jeffjade.com/2015/05/17/2015-05-17-lua-ldoc/

参考文章链接A

参考文章链接B

参考文章链接C