使用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

参考文章链接A 参考文章链接B 参考文章链接C

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏AzMark

Python 学习之进程与线程 「 上 」

进程:对于操作系统来说,一个任务就是一个进程(Process),比如打开一个浏览器(任务)就是启动一个浏览器进程。进程是系统中程序执行和资源分配的基本单位,每个...

742
来自专栏IT可乐

Linux系列教程(二十)——Linux的shell概述以及如何执行脚本

  从这篇博客开始,我们将进入Linux的shell脚本的学习,这对于Linux学习爱好者而言是特别重要的一节,也是特别有意思的一节,shell 脚本就像我们知...

2188
来自专栏开源优测

python selenium2示例 - 利用excel实现参数化

前言 在进行软件测试或设计自动化测试框架时,一个比可避免的过程就是: 参数化,在利用python进行自动化测试开发时,通常会使用excel来做数据管理,利用xl...

3267
来自专栏逆向与安全

GDB多线程调试分析

多线程调试的主要任务是准确及时地捕捉被调试程序线程状态的变化的事件,并且GDB针对根据捕捉到的事件做出相应的操作,其实最终的结果就是维护一根叫thread li...

1160
来自专栏JarvanMo的IT专栏

Node.js文件路径的坑

没错,我想读取system-config.json中的配置。刚开始,无论如何也读不到,连个错误信息也没有。调试了一番,终于出了一个错误信息: no such ...

1884
来自专栏程序员同行者

django权限管理(Permission)

1.1K4
来自专栏开源优测

python selenium - 利用excel实现参数化

前言 在进行软件测试或设计自动化测试框架时,一个比可避免的过程就是: 参数化,在利用python进行自动化测试开发时,通常会使用excel来做数据管理,利用xl...

3798
来自专栏Linux驱动

第4阶段——制作根文件系统之分析init进程(2)

本节目标: (1) 了解busybox(init进程和命令都放在busybox中) (2) 创建SI工程,分析busybox源码来知道init进程做了哪些事情 ...

2529
来自专栏玄魂工作室

怎样学Python之第十九课 高级文件输入和输出

欢迎回来!如果您还记得以前的几次培训课程,我们介绍了基本的文件I/O。 这是使我们的脚本适用于现实生活场景中的一个非常重要的步骤,今天我们将要深入这些概念。 我...

3345
来自专栏Java工程师日常干货

【SpringBoot专题】多环境配置及swagger前言多环境配置分析swagger

在上一篇博客《【SpringBoot专题】快速体验 》中已经带领大家初步了解了SpringBoot,本篇博客将为大家介绍多环境配置、swagger等相关内容。

1114

扫码关注云+社区

领取腾讯云代金券