【Lua】LDoc生成Lua文档工具的使用
LDoc的一个优点就是,它的目的是为了和LuaDoc兼容并且拓展LuaDoc的功能而制作的,所以LuaDoc能够使用的标签LDoc也都可以使用。
LDoc还有一些其他的LuaDoc不具备的优点,比如
- LDoc可以生成Markdown格式的文档.
- LDoc生成的文档也也更加美观等等。
LDoc虽然可以针对某个lua文件生成文档,但是更加推荐的方式是通过config.ld来对需要生成文档的项目进行配置,之后,只要在config.ld所在的文档使用ldoc .
即可对配置好的文件夹生成文档。
1、安装
从github主页:https://github.com/stevedonovan/ldoc上下载LDoc
2、使用方法
2.1 配置config.ld,创建一个config.ld配置信息如下:
选项含义说明:
1、file —— 需要生成文档的源文件位置,需要是一个文件目录,当添加了这个目录之后,它的所有子目录默认也会被扫描,比如下图中的
sub.submodule就是处于子目录下的模块,也会一并显示在文档中。
添加了项目名称后,它生成的文档样式如下:
2.2、注释说明
在项目中,我们的每一个lua文件可以看做是一个模块,模块的文档标注如下:
样例:
注意到上文中的---
了吗?这里是有深意的。
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)。我们将依次讲解这四种东西怎么写出可被解析的注释。
1. 对table的注释:
如果,我们想添加一个table的时候,需要这么写注释:
---
-- 这是一个人的类,它有姓名和年龄两个属性
-- 在这个类中,我们规定了name和age的类型
-- @string name
-- @int age
-- @tparam person father
person = {
name = "",
age = 0,
father = nil
}
这段注释代码,生成的文档样例如下:
2、对exported function的注释
如果我们添加了一个exported function时,我们需要对这个函数进行解释,比如这种:
--- 通过这个方法可以得到该Person的父亲
-- @treturn person father
function person:getFather( )
return self.father
end
或者这种更加复杂的导出函数:
--- 解决一个平方根问题
-- @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标签来进行用法实例
上面函数的文档样式为:
3、local function和fields
如果我们添加了一个local function时,我们通常是不需要写注释的,因为这种函数是私有的不应当放在文档中。
如果想要添加fields,fields一般是常量,可以将一组相关的常量放在一个表里,这种写法和table的写法相似,就不再赘述。
4、类型标签
上文中有两种特殊的参数和返回值,即tparam和treturn,这两种类型都是可以自定义的,其语法如下:
tparam <typename> <comment>
比如,我需要一个Person的参数时,我就会这样声明tparam Person need a Person
,其中Person就是typename,need a Person就是comment
3、LDoc中的标签
通过上述的讲解,我们发现LDoc中十分好用的一点就是可以标识某个参数的类型,那么LDoc到底支持哪些类型呢?
可以通过一个列表来说明:
- string
- number
- int
- bool
- func 标识
‘function’
- tab 标识
‘table’
- thread 标识
’coroutine‘
二、使用实例
在文件夹中新建一个文件usage.lua
Lua, pasted 3 seconds ago:
|
2、创建config.ld文件
3、生成doc
在config.ld所在的目录执行lua ldoc.lua . 即可以生成doc文件夹,或者在其他目录执行
lua ldoc.lua -c config_path 即可在config.ld指定的file路径中生成doc
注:
如上是在其他目录执行 E:\Workspace\Cocos2dxProject\ldoc_test 目录下的config.ld文件,因此使用如下命令即可:
4、生成的doc文件如下:
【Lua】LDoc生成Lua文档工具的使用的更多相关文章
- 生成chm文档工具- Sandcastle -摘自网络
Sandcastle是微软官方的文档生成工具,NDoc开发停止后,这个貌似也是唯一的一个这方面的工具.它从dll文件及其xml注释文件能够 生成完整的帮助文档,支持多种生成格式(Helpe1x:chm ...
- .Net魔法堂:提取注释生成API文档
一.前言 在多人协作的项目中,除了良好的代码规范外,完整的API文档也相当重要.通过文档我们快速了解系统各模块的实际接口,及其使用场景.使用示例,一定程度上降低沟通成本,和减少后期维护中知识遗失等风险 ...
- .net 提取注释生成API文档 帮助文档
提取注释生成API文档 一.前言 在多人协作的项目中,除了良好的代码规范外,完整的API文档也相当重要.通过文档我们快速了解系统各模块的实际接口,及其使用场景.使用示例,一定程度上降低沟通成本,和 ...
- Java 导出数据库表信息生成Word文档
一.前言 最近看见朋友写了一个导出数据库生成word文档的业务,感觉很有意思,研究了一下,这里也拿出来与大家分享一波~ 先来看看生成的word文档效果吧 下面我们也来一起简单的实现吧 二.Java 导 ...
- [.NET] WebApi 生成帮助文档及顺便自动创建简单的测试工具
==========最终的效果图========== ==========下面开始干活:生成帮助文档========== 一.创建 WebApi 项目 二.找到 HelpPageConfig.cs 并 ...
- 基于数据库的自动化生成工具,自动生成JavaBean、自动生成数据库文档等(v4.1.2版)
目录: 第1版:http://blog.csdn.net/vipbooks/article/details/51912143 第2版:htt ...
- 基于数据库的代码自动生成工具,生成JavaBean、生成数据库文档、生成前后端代码等(v6.0.0版)
TableGo v6.0.0 版震撼发布,此次版本更新如下: 1.UI界面大改版,组件大调整,提升界面功能的可扩展性. 2.新增BeautyEye主题,界面更加清新美观,也可以通过配置切换到原生Jav ...
- 快速根据注释生成接口文档网页工具——Apidoc的使用教程
1,安装Node.js的npm工具环境: 如有不懂,请看我的博客:“https://blog.csdn.net/sinat_28371057/article/details/81612661“ 2,n ...
- 干掉 Postman?测试接口直接生成API文档,这个工具贼好用
大家好,我是小富~ 前几天粉丝群有小伙伴问,有啥好用的API文档工具推荐,无意间发现了一款工具,这里马不停蹄的来给大家分享一下. ShowDoc一个非常适合团队的在线API文档工具,也支持用docke ...
随机推荐
- Chrome各个版本小常识
摘要: 近期在网上看到chrome有个金丝雀版,第一次看到这个版本,所以就将chrome的各个版本进行了了解,chrome是前端开发最好用的工具,不仅仅是它的调试工具,还有他对HTML5/CSS3的兼 ...
- pcduino 无法打开usb摄像头。
1.sudo ./demon http://www.oschina.net/question/994181_118098 2.usb camera interfarce switch :http: ...
- Java精选笔记_Java API
String类 String类的初始化 String是一个特殊的对象,一旦被初始化,就不会被改变 1.使用字符串常量直接初始化一个String对象 String s1="abc" ...
- Extjs学习笔记--(三,调试技巧)
FireFox 1.firedebug(略) 2.illuminations 在illuminations页面可也看到缩写的extjs的代码,同时可以进行相应的调试 3,Firedebug AutoC ...
- php-新特性,生成器的创建和使用
mark 一下~ http://laravelacademy.org/post/4317.html
- ping命令和telnet命令
1.检查能不能连接上远程主机 ping 主机ip 2.检查远程主机端口是不是开放 telnet 198.10.10.69 1521 Trying 198.10.10.69...Connected t ...
- 原生JS,实现图片可拖拽,并且移动四个角和四条变能够自由变换图片大小
网上搜的资料,源码如下: <!DOCTYPE html> <html> <head> <meta charset="UTF-8"> ...
- 【python系列】python2.x和python3.x的区别
刚接触python使用的是python2.x的书籍,但是发现python3.x和python2.x有不小的区别,以下做一些记录 性能 Py3.0运行 pystone benchmark的速度比Py2. ...
- 使用Android Studio调试内存问题
http://blog.csdn.net/yutao52shi/article/details/50055669 前言 内存问题对于Android开发者是永远的痛.如果一个android程序员说他没有 ...
- {sharepoint} SetPermission
using System; using System.Collections.Generic; using System.Linq; using System.Text; using Microsof ...