文档章节

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

王选易
 王选易
发布于 2013/12/30 16:04
字数 1480
阅读 2.8K
收藏 5

如果你觉得本文的排版不舒服,您可以下载我的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标签来进行用法实例

上面函数的文档样式为:

在此输入图片描述

####local function和fields

如果我们添加了一个local function时,我们通常是不需要写注释的,因为这种函数是私有的不应当放在文档中。

如果想要添加fields,fields一般是常量,可以将一组相关的常量放在一个表里,这种写法和table的写法想死,就不再赘述。

####类型标签

上文中有两种特殊的参数和返回值,即tparam和treturn,这两种类型都是可以自定义的,其语法如下:

tparam <typename> <comment>

比如,我需要一个Person的参数时,我就会这样声明tparam Person need a Person,其中Person就是typename,need a Person就是comment

###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

###拓展阅读

如果你还想了解更多关于LDoc的细节,可以访问作者的官方文档:LDoc

© 著作权归作者所有

王选易

王选易

粉丝 99
博文 20
码字总数 20066
作品 3
南京
程序员
私信 提问
加载中

评论(3)

王选易
王选易 博主
@红薯 为什么我的文章没有出现在最新博客里啊
王选易
王选易 博主

引用来自“ChildhoodX”的评论

哎呦,我去,老王,这篇博客对我来说真是及时雨!!!!

其实我也在写文档。。。
ChildhoodAndy
ChildhoodAndy
哎呦,我去,老王,这篇博客对我来说真是及时雨!!!!
lua第三方库

luaCom 支持COM调用 LuaDoc 支持lua代码的文档生成 LuaExpat 支持XML解析 LuaFileSystem 文件系统访问 LuaLogging 基于log4j的日志 LuaProfiler 性能测试工具 LuaSocket 网络库,支持HTTP,FT...

mickelfeng
2016/09/21
270
0
【深入Lua】理解Lua中最强大的特性-coroutine(协程)

---------- 点击进入我的新博客 coroutine基础 Lua所支持的协程全称被称作协同式多线程(collaborative multithreading)。Lua为每个coroutine提供一个独立的运行线路。然而和多线程不同的地...

王选易
2013/12/21
4.7W
15
cheerayhuang/quickserver

Quick-Server 基于OpenResty的服务器框架 最新版本 0.5.0 介绍 Quick Server 为开发者提供一个稳定可靠,可伸缩的服务端架构,让开发者可以使用 Lua 脚本语言快速完成服务端的功能开发。 主要...

cheerayhuang
2015/01/21
0
0
Lua-C++ 绑定库--LuatinkerE

LuatinkerE Lua-C++绑定库"luatinker"的C++14和Lua 5.3扩展版本。 使用大量C++14特性Variadic Template 和 indexsequence, SFINAE enableif 和 typetraits, tuple, function, forwardref, d......

yanwei1983
2016/08/10
266
0
xmake插件使用之doxygen文档生成

这个doxygen插件比较简单,说白了就是一键生成工程文档,只需要执行下面这行命令就行了 当然你也可以指定输出目录,可以工程源码目录: 生成的文档中,工程名和版本号,就是xmake.lua中通过如...

ruki
2016/06/22
15
0

没有更多内容

加载失败,请刷新页面

加载更多

1.4掌握日志工具的使用——Android第一行代码(第二版)笔记

Android中的日志工具类是Log(android.util.Log),这个类中提供了如下5个方法来供我们打印日志。 Log.v():用于打印那些最为琐碎的、意义最小的日志信息。对应级别verbose,是Android日志里面...

Cy23
29分钟前
33
0
System.currentTimeMillis和System.nanoTime

精度与 精确 我想知道的是在更新对象在游戏中的位置时应该使用System.currentTimeMillis()还是System.nanoTime() ? 他们的运动变化与自上次通话以来经过的时间成正比,我想尽可能地精确...

javail
35分钟前
31
0
Linux就该这么学 -- 命令 - man

man命令用于查看某个命令的帮助信息 格式:man 命令名称 man man 表示查询man命令本身的帮助信息 man ls 表示查询ls命令的帮助信息 由于命令查询出来的内容一般都比较多,所以要了解相关的组...

jionzhao
37分钟前
47
0
Bmob后端云(云数据库表的具体操作)

1.注册创建应用请看该博客 Bomb基本操作 2.创建云数据库表 2.1 步骤一: 点击添加表 2.2 步骤二: 填写表信息 2.3 表结构详解 3. 操作表 3.1 添加一个表字段 3.1.1 步骤一: 点击添加列 3.1.2 ...

漫路h
39分钟前
37
0
Spring Bean的生命周期?

Spring Bean的生命周期简单易懂。在一个bean实例被初始化时,需要执行一系列的初始化操作以达到可用的状态。同样的,当一个bean不在被调用时需要进行相关的析构操作,并从bean容器中移除。 ...

无名氏的程序员
39分钟前
60
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部