• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    公众号

【Lua】LDoc生成Lua文档工具的使用

原作者: [db:作者] 来自: [db:来源] 收藏 邀请
参考资料:
  http://my.oschina.net/wangxuanyihaha/blog/188909
 
LDoc介绍:
    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 .即可对配置好的文件夹生成文档。

 

 

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 


   [ raw code | fork ]
 

Lua, pasted 3 seconds ago: 
--[[-------- A simple module with examples. Even without markdown formatting, blank lines are respected. @module usage ]] local usage = {} local helper --- a local helper function. -- @local function helper () end ---------- -- A simple vector class. -- -- Supports arithmetic operations. -- @usage -- v = Vector.new {10,20,30} -- assert (v == Vector{10,20,30}) -- @type Vector local Vector = {}
usage.Vector = {} ---------- -- Create a vector from an array `t`. -- `Vector` is also callable! function Vector.new (t) end -- note that @function may have modifiers. Currently -- we aren't doing anything with them, but LDoc no longer -- complains (issue #45). Note also that one needs -- explicit @param tags with explicit @function; 'static' -- methods must have a @constructor or a @static tag. ---------- -- Create a vector from a string. -- @usage --  v = Vector.parse '[1,2,3]' --  assert (v == Vector.new {1,2,3}) -- @function[kind=ctor] parse -- @static -- @param s function Vector.parse (s) end -------- -- Compare two vectors for equality. function Vector:__eq (v) end ---------- -- Add another vector, array or scalar `v` to this vector. -- Returns new `Vector` -- @usage assert(Vector.new{1,2,3}:add(1) == Vector{2,3,4}) function Vector:add (v) end ---------- -- set vector options. `opts` is a `Vector.Opts` table. function Vector:options (opts) end --[[----------------- @table Vector.Opts Options table format for `Vector:options`  * `autoconvert`:  try to convert strings to numbers  * `adder`: function used to perform addition and subtraction  * `multiplier`: function used to perform multiplication and division @usage  v = Vector {{1},{2}}  v:options {adder = function(x,y) return {x[1]+y[1]} end}  assert(v:add(1) == Vector{{2},{3}}) ]] return usage

 

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文件如下:

 


鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
上一篇:
iOS中Lua脚本应用笔记一:脚本概念相关发布时间:2022-07-22
下一篇:
用ldoc给cocos2dx-lua项目生成API文档发布时间:2022-07-22
热门推荐
热门话题
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

在线QQ客服
地址:深圳市南山区西丽大学城创智工业园
电邮:jeky_zhao#qq.com
移动电话:139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap