使用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。即便是类似如下比较复杂的函数,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
- Android-Universal-Image-Loader 图片异步加载类库的使用
- 工作组模式下专用队列(Private Queue)如何引用远程队列路径
- haproxy反向代理环境部署(http和https代理)
- 网站速度优化模块HttpCompressionModule
- mysql启动后随即关闭问题解决(ibdata1文件损坏导致)
- webvirtmgr-重命名kvm虚拟机的名称
- Lucene 2.0最基本的入门代码
- 网站每日PV/IP统计/总带宽/URL统计脚本分享(依据网站访问日志)
- 查看服务器系统资源(cpu,内容)利用率前几位的进程的方法
- 腾讯云平台部总经理陈磊:大数据背后的技术支撑
- DataSet与Xml相互转化
- SqlTransaction事务使用示例
- nginx的web缓存服务环境部署记录
- nginx反向代理+缓存开启+url重写+负载均衡(带健康探测)的部署记录
- JavaScript 教程
- JavaScript 编辑工具
- JavaScript 与HTML
- JavaScript 与Java
- JavaScript 数据结构
- JavaScript 基本数据类型
- JavaScript 特殊数据类型
- JavaScript 运算符
- JavaScript typeof 运算符
- JavaScript 表达式
- JavaScript 类型转换
- JavaScript 基本语法
- JavaScript 注释
- Javascript 基本处理流程
- Javascript 选择结构
- Javascript if 语句
- Javascript if 语句的嵌套
- Javascript switch 语句
- Javascript 循环结构
- Javascript 循环结构实例
- Javascript 跳转语句
- Javascript 控制语句总结
- Javascript 函数介绍
- Javascript 函数的定义
- Javascript 函数调用
- Javascript 几种特殊的函数
- JavaScript 内置函数简介
- Javascript eval() 函数
- Javascript isFinite() 函数
- Javascript isNaN() 函数
- parseInt() 与 parseFloat()
- escape() 与 unescape()
- Javascript 字符串介绍
- Javascript length属性
- javascript 字符串函数
- Javascript 日期对象简介
- Javascript 日期对象用途
- Date 对象属性和方法
- Javascript 数组是什么
- Javascript 创建数组
- Javascript 数组赋值与取值
- Javascript 数组属性和方法
- Hexo博客Next主题浏览统计不显示
- 视频上云网关平台EasyCVR使用海康SDK拉流协议分析
- 计算机网络物理层习题
- 从数据库中查询马上过生日的人并统计各年龄段及性别所占的人数
- Ubuntu19.10 中安装 JDK
- 在 Ubuntu19.10 上安装 wine 并安装 QQ 等软件
- wordpress迁移至hugo及其自动化发布文章全记录
- 视频流媒体平台EasyNVR硬件设备使用华科云arm版如何修改为固定IP?
- 详解 IP 地址
- k8s解决pod调度不均衡的问题
- 如何获取视频流媒体服务器EasyNVR的临时授权机器码?
- Mybatis-Plus常用注解
- IDEA 你不知道小技巧——后缀法自动生成代码(Postfix Completion)
- Mybatis-Plus使用乐观锁
- k8s基础之调度策略(二)