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

原文首贴链接http://jeffjade.com/2015/05/17/2015-05-17-lua-ldoc/

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

随机推荐

  1. DataGridView 在下拉框添加下来事件

    DataGridView中有一种下拉框式的列,给这个列添加下拉事件时需要转化一下才可以绑定下拉事件 /// <summary> /// 服务类型 /// </summary> ...

  2. 某预约系统分析 &gt; 某区公共自行车租车卡在线预约,关于如何提高成功概率

    概诉 网上提交预约申请单,线下面交完成实体卡的交付和办理. 本文主要从技术角度分析预约页面,仅供初学者技术交流使用. 表单输入和校验 系统通过2步的确认点击到达信息输入页面. 地址:/bjggzxc/ ...

  3. jQuery滚动数字

    <ul class="dateList"> <li class="one"> <p class="titleName&q ...

  4. windows下用navicat远程链接虚拟机Linux下MySQL数据库

    今天想用navicat远程连接虚拟机中的MySQL数据库,一直连不上,在网上搜索了一下,发现原因是MySQL对远程用户登陆的授权问题.这里说一下我的解决方法.(本人小白) 首先,我用navicat去远 ...

  5. July 1st, Week 27th Friday, 2016

    It does not do to dwell on dreams, and forget to live. 不要生活在梦里,不要沉醉于空想而疏忽了生活. Stand straightly, and ...

  6. windows进程中的内存结构[转载]

    在阅读本文之前,如果你连堆栈是什么多不知道的话,请先阅读文章后面的基础知识. 接触过编程的人都知道,高级语言都能通过变量名来访问内存中的数据.那么这些变量在内存中是如何存放的呢?程序又是如何使用这些变 ...

  7. linux+apache url大小写敏感问题

    Linux对文件目录大小写敏感,URL大小写敏感会导致网页打不开,解决方法之一是启用Apache的mod_speling.so模块. 1.确认/usr/lib/httpd/modules目录下是否存在 ...

  8. Erlang安装笔记

    今天,为了安装RabbitMQ,需要安装Erlang,中间遇到了一些坑,记录下来. 1. 下载Erlang安装包 http://www.erlang.org/downloads http://erla ...

  9. Linux 串口使用

    1. 安装串口调试工具minicom sudo apt-get install minicom 2. 查看串口端口 cfm@cfm880:~$ dmesg | grep tty[ 0.000000] ...

  10. [读书笔记]ASP.NET的URL路由引擎

    作用 一般的URL: 举例:http://www.myapp.com/app.aspx?id=2&sessionid=29320xafafa02fa0zga0g8a0z 缺点: 不美观,不清晰 ...