LDoc介绍：
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 .即可对配置好的文件夹生成文档。
1、安装
从github主页：https://github.com/stevedonovan/ldoc上下载LDoc
2、使用方法
2.1 配置config.ld，创建一个config.ld配置信息如下：
选项含义说明：
1、file —— 需要生成文档的源文件位置，需要是一个文件目录，当添加了这个目录之后，它的所有子目录默认也会被扫描，比如下图中的
sub.submodule就是处于子目录下的模块，也会一并显示在文档中。
添加了项目名称后，它生成的文档样式如下：
2.2、注释说明
在项目中，我们的每一个lua文件可以看做是一个模块，模块的文档标注如下：
样例：
注意到上文中的---了吗？这里是有深意的。
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）。我们将依次讲解这四种东西怎么写出可被解析的注释。
1. 对table的注释:
如果，我们想添加一个table的时候，需要这么写注释：
---
-- 这是一个人的类，它有姓名和年龄两个属性
-- 在这个类中，我们规定了name和age的类型
-- @string name
-- @int age
-- @tparam person father
person = {
name = "",
age = 0,
father = nil
}这段注释代码，生成的文档样例如下：
2、对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标签来进行用法实例
上面函数的文档样式为：
3、local function和fields
如果我们添加了一个local function时，我们通常是不需要写注释的，因为这种函数是私有的不应当放在文档中。
如果想要添加fields，fields一般是常量，可以将一组相关的常量放在一个表里，这种写法和table的写法相似，就不再赘述。
4、类型标签
上文中有两种特殊的参数和返回值，即tparam和treturn，这两种类型都是可以自定义的，其语法如下：
tparam <typename> <comment> 比如，我需要一个Person的参数时，我就会这样声明tparam Person need a Person，其中Person就是typename，need a Person就是comment
3、LDoc中的标签
通过上述的讲解，我们发现LDoc中十分好用的一点就是可以标识某个参数的类型，那么LDoc到底支持哪些类型呢？
可以通过一个列表来说明：
- string
- number
- int
- bool
- func 标识
‘function’ - tab 标识
‘table’ - thread 标识
’coroutine‘
二、使用实例
在文件夹中新建一个文件usage.lua
Lua, pasted 3 seconds ago: |
Link: http://codepad.org/JTy1TXR4 [ raw code | fork ] | |
2、创建config.ld文件
3、生成doc
在config.ld所在的目录执行lua ldoc.lua . 即可以生成doc文件夹，或者在其他目录执行
lua ldoc.lua -c config_path 即可在config.ld指定的file路径中生成doc
注：
如上是在其他目录执行 E:\Workspace\Cocos2dxProject\ldoc_test 目录下的config.ld文件，因此使用如下命令即可：
4、生成的doc文件如下：
