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

最新推荐文章于 2020-03-03 23:45:33 发布

weixin_33744854

最新推荐文章于 2020-03-03 23:45:33 发布

阅读量188

点赞数

文章标签： lua python markdown

原文链接：https://my.oschina.net/wangxuanyihaha/blog/188909

版权

2019独角兽企业重金招聘Python工程师标准>>>

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

###介绍

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 .即可对配置好的文件夹生成文档。

###安装

LDoc唯一依赖的库是Penlight,PenLight又依赖于LuaFileSystem,这些库在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的时候，需要这么写注释：

<!-- lang: lua -->
---
-- 这是一个人的类，它有姓名和年龄两个属性
-- 在这个类中，我们规定了name和age的类型
-- @string name
-- @int age
-- @tparam person father
person = {
	name = "",
	age = 0,
	father = nil
}

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

在此输入图片描述

####对exported function的注释

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

<!-- lang: lua -->
--- 通过这个方法可以得到该Person的父亲
-- @treturn person father
function person:getFather(  )
	return self.father
end

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

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

上面函数的文档样式为：

在此输入图片描述