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

使用Ldoc给Lua生成文档的更多相关文章

  1. 使用 Swagger 自动生成 ASP.NET Core Web API 的文档、在线帮助测试文档(ASP.NET Core Web API 自动生成文档)

    对于开发人员来说,构建一个消费应用程序时去了解各种各样的 API 是一个巨大的挑战.在你的 Web API 项目中使用 Swagger 的 .NET Core 封装 Swashbuckle 可以帮助你 ...

  2. 使用PhpDocumentor生成文档

    一,网站根目录执行 $ composer require --dev phpdocumentor/phpdocumentor 二,进入vendor/bin/目录执行 $phpdoc -d D:\ser ...

  3. doxygen的使用(一)配置并生成文档

    原创文章,欢迎阅读,禁止转载. doxygen是个好用的文档生成工具,他的强大功能有很多介绍,我就不说了.自带的chm帮助手册很全面,包括功能.注释规范.怎么配置.工具用法等.doxygen的用法共3 ...

  4. 配置WCF同时支持WSDL和REST,swaggerwcf生成文档

    配置WCF同时支持WSDL和REST,SwaggerWCF生成文档 VS创建一个WCF工程,通过NuGet添加SwaggerWcf 创建完成后通过 程序包管理控制台 pm>Install-Pac ...

  5. ASP.NET Core 1.0 中使用 Swagger 生成文档

    github:https://github.com/domaindrivendev/Ahoy 之前文章有介绍在ASP.NET WebAPI 中使用Swagger生成文档,ASP.NET Core 1. ...

  6. 为Unity项目生成文档(二)

    Unity项目生成文档 接着上篇文章:为Unity项目生成文档(一) .Net项目可在VS配置XML 我们可以在VS中通过配置来生成xml文件,但是unity的project,就算同样配置了xml文档 ...

  7. doc2vec 利用gensim 生成文档向量

    利用gensim 直接生成文档向量 def gen_d2v_corpus(self, lines): with open("./data/ques2_result.txt", &q ...

  8. 使用eclipse生成文档(javadoc)

    使用eclipse生成文档(javadoc)主要有三种方法:1,在项目列表中按右键,选择Export(导出),然后在Export(导出)对话框中选择java下的javadoc,提交到下一步.在Java ...

  9. xcode 自动添加注释,生成文档

    一.自动生成注释代码        添加一个快捷键,生成 注释代码        ThisService 下载连接:http://wafflesoftware.net/thisservice/     ...

随机推荐

  1. 如何在VS 2010中使用 VS2013的解决方案(转)

    今天要用VS2010打开VS2013,一直觉得VS2010到VS2012只是界面上扁平化的改变,平台工具集有改变但很大程度上可能向上兼容.在网上搜了一些文章,其中有一篇说到一个观点:        从 ...

  2. TabSiPlus发布1749版本

    拖了几天,终于可以发布了,下载地址如下: http://www.winmsg.com/download/TabSiPlus_0_99b2_1749.rar 这个包里没有附带VC的运行库,考虑到大多数人 ...

  3. SQLSERVER跨数据库操作 ---- sp_addlinkedserver

    由于项目需要跨数据库进行相应的sql操作(这里遇到的是sqlserver的A库,到sqlserver的B库) sp_addlinkedserver [ @server = ] ' server ' [ ...

  4. maven 依赖查询

    该文章源地址:http://xiejianglei163.blog.163.com/blog/static/1247276201362733217604/ 为方便个人使用,转载于此处. http:// ...

  5. Java for LeetCode 168 Excel Sheet Column Title

    Given a positive integer, return its corresponding column title as appear in an Excel sheet. For exa ...

  6. ZOJ 2404 Going Home 【最小费用最大流】

    思路: 把房子和人看成点,加上源点和汇点. 源点和每个人连容量为1,权值为0的边. 每个人和每个房子连容量为1,权值为距离的边. 每个房子和汇点连容量为1,权值为0的边. #include<st ...

  7. Codeforces 631C

    题意:给定n和m. 给定一个长度为n的序列,m次操作. 接下来m次操作,每行第一个数若为1,则增序排列,若为2则降序排列,第二个数是排列的范围,即从第一个数排序到第某个数. 思路: 首先,对于其中范围 ...

  8. [swustoj 404] 最小代价树

    最小代价树(0404) 问题描述 以下方法称为最小代价的字母树:给定一正整数序列,例如:4,1,2,3,在不改变数的位置的条件下把它们相加,并且用括号来标记每一次加法所得到的和. 例如:((4+1)+ ...

  9. java技术栈:一、java编程语言概述

    Java是一种编程语言,起源于20世纪90年代初Sun公司的一个叫Green的项目,该项目主要目的是是开发嵌入家用电器的分布式软件系统,从而使电器更加智能化.因为项目小组成员皆为C++的高手(那个年代 ...

  10. SPRING IN ACTION 第4版笔记-第二章-003-以Java形式注入Bean、@Bean的用法

    1. package soundsystem; import org.springframework.context.annotation.Bean; import org.springframewo ...