文档章节

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

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

3 月,跳不动了?>>>


如果你觉得本文的排版不舒服,您可以下载我的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
312
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
275
0
xmake插件使用之doxygen文档生成

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

ruki
2016/06/22
19
0

没有更多内容

加载失败,请刷新页面

加载更多

R语言实现voronoi treemap可视化

今天带来一篇承诺虾神的R语言可视化博客。关于voronoi treemap的可视化。 1 任务布置过程 感谢虾神,刀爷和魄爷实名出镜。 事实上这是刀爷看到澎湃美数课发的一篇推送文章其中一张图产生的疑...

胖胖雕
9分钟前
7
0
如何从列表中随机选择一个项目? - How to randomly select an item from a list?

问题: Assume I have the following list: 假设我有以下列表: foo = ['a', 'b', 'c', 'd', 'e'] What is the simplest way to retrieve an item at random from this list? 从此列表中随机......

javail
今天
21
0
Gradle 6 针对已有的构建如何创建一个构建扫描

有关构建扫描的定义为: 构建扫描(build scan)是一个中心化并且可以共享的构建记录。这个构建记录通常能够告诉在构建中发生了什么并且为什么会发生。 通过应用构建扫描插件到你的项目中,你...

honeymoose
今天
17
0
C语言动态内存分配:(一)malloc/free的实现及malloc实际分配/释放的内存

一、malloc/free概述 malloc是在C语言中用于在程序运行时在堆中进行动态内存分配的库函数。free是进行内存释放的库函数。 1、函数原型 #include <stdlib.h> void *malloc( size_t size ); v...

shzwork
今天
19
0
什么是JavaBean? - What is a JavaBean exactly?

问题: I understood, I think, that a "Bean" is a Java class with properties and getters/setters. 我认为,“ Bean”是具有属性和getter / setter的Java类。 As much as I understand,......

技术盛宴
今天
27
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部