专栏首页游戏开发之旅Lua生成的LDoc文档注释规范

Lua生成的LDoc文档注释规范

标签

  • @module 模块, 一般一个文件就是一个模块.
  • @classmod 和 @module 类似, 但是用来描述 class, 用这个标签后, 生成的文档中 Module 文字会变成 Class.
  • @submodule 如果一个模块的内容被分到了好几个文件中, 那么就可以再其他文件中用 submodule 来定义, 后面跟上master module的名字.
  • @script 和 @module 类似, 生成的文档中 Module 文字会变成 Script.

以上几个标签都是project-level, 意味着每个文件中只能包含它们其中的一个, 否则生成时就会提示 Module already declared! 错误.

  • @author (multiple), @copyright, @license, @release 这几个啥意思就不必说了吧, 值得一提的是它们必须放在project-level,如 @module 标签下.
  • @function, @lfunction. 用来描述函数. @function 一般情况下不用加, 只需要给函数加上—注释就可以.@lfunction 用来表示一个局部函数, 但是ldoc默认是不会导出局部变量和函数的.
  • @param @int, @string, @bool, @func, @tab, @thread 用来描述函数参数, 后面几个指定了参数类型.
  • @return 函数的返回值, 函数的返回值可能有多种, 因此 @return 在一个函数中也是可以多次使用的
  • @raise 这个函数可能抛出的错误
  • @local 最大的作用是使得一个函数不被导出, 除非使用了(unless –all)
  • @see 引用文档的其他内容, 同一模块的话直接 @see xxx, 不同模块的话需要加上模块名 @see xxmodule.xxfunc
  • @usage 给出函数的用例, 可以分多行来写
  • @fixme, @todo 和 @warning , 意思大家应该都懂. 但是必须在函数体内部并且以 — 开头才能生效.

以上几个标签都是描述function的一些行为的

  • @table 描述一个table, 也可以不加, 只需要给table加上—注释就可以.
  • @field 用来描述table中的一个字段
  • @section 用来把一个模块分隔成好几块
  • @type 和 @class 的作用差不多, 但不能与 @class 同时存在. 一个文件中可以有多处 @type , 会和@section 似的,把文件分隔成好多份.
  • @within 用来形容函数和table, 指定它们属于哪个section, 可以指定不存在的一个section, 会自动创建一个

函数的一些高级用法

显示参数的类型

函数参数@param 是不指明具体类型的, 若想指明的话可以用 @int, @string, @bool, @func, @tab, @thread 几个标签来.

可选参数与默认值

可选参数的标记是自参数标签后紧跟 [opt] 来标识, 默认值则是 [opt=xx]. 让我们看一个官方的示例:

--- a function with typed args.
-- @string name person's name
-- @int age
-- @string[opt='gregorian'] calender optional calendar
-- @int[opt=0] offset optional offset
-- @treturn string
function one (name,age,...)
end
----> displayed as: one (name, age [, calender='gregorian' [, offset=0]])

多种返回值

一个函数不同的情况可能返回不同的值, 意义也都不一样, 那么怎么来表示呢? 答案是在 @return 后紧跟 x 来标识. 生成出来的文档是用 Or 来列出这些不同的返回值的.

config.ld 的字段说明

ldoc 运行时有一堆参数可以传递, 在终端中去做比较麻烦, 修改也不太方便. 因此我们可以创建一个config.ld 配置文件来做这个事情, ldoc . 表示在当前目前下查找 config.ld 文件, ldoc -c path/to/myconfig.ld 读取特殊的目录的配置文件. 其实 config.ld 就是一个lua文件, 填写时需要遵循lua语法.

  • file 可以是一个文件名或者目录名, 如: file = ‘test.lua’. file 也可以是一个table, 这时里面可以填写文件数组或目录数组, 同时也可以包含另一个特殊的数组 exclude, 表明要排除的文件或目录
  • project 项目的名称, 会出现在文档的左上角. 默认为 ldoc
  • title 页面的名称, 默认为 Reference
  • all 导出 local 的 function
  • output 导出 html 的名字, 默认是 index
  • dir 导出目录的名字, 默认是 doc
  • colon 使用冒号风格代替 @ 风格的 tag
  • boilerplate 忽略所有源文件中的首个注释(块), 比如: license 注释.
  • ext 输出文件的后缀(默认为 html)
  • one 文档使用单列的布局
  • style, template 指定模板和样式的目录. 在 config.ld 中它也可以为 true , 表示使用和配置文件同一目录的模板.
  • merge 允许文档从不同的文件合并同名的 module , 而不是产生多个module.

附录:

官方文档: 这里 github地址: 这里

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • Python爬虫实践

    bering
  • 利用 three.js 开发微信小游戏的尝试

    这是一次利用 three.js 开发微信小游戏的尝试,并不能算作是教程,只能算是一篇笔记吧。

    bering
  • uinty中对Xml文件的操作

    版权声明:本文为博主原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明...

    bering
  • python教程(八)·文件操作

    由于离高考越来越近,博主打算本篇文章过后,暂停本系列教程的更新,等到高考完后再继续本系列教程,请谅解!

    py3study
  • (56) 文件概述 / 计算机程序的思维逻辑

    我们在日常电脑操作中,接触和处理最多的,除了上网,大概就是各种各样的文件了,从本节开始,我们就来探讨文件处理,本节主要介绍文件有关的一些基本概念和常识,Java...

    swiftma
  • Linux文件I/O函数

    版权声明:本文为博主原创文章,转载请注明博客地址: ...

    zy010101
  • 操作系统 文件管理 概述

    计算机的主要功能之一就是对数据进行数值或非数值计算。系统软件必须提供数据存储、数据处理、数据管理的基本功能。数据管理是通过文件管理的方式来完成的,而目录又是建立...

    Debug客栈
  • python基础(4):Python读写文件实际操作的五大步骤

    from: http://developer.51cto.com/art/201003/187960.htm Python读写文件在计算机语言中被广泛的应用,如...

    用户1177713
  • 【C语言基础】fopen函数使用

    r代表read的简写,+代表可读可写,w代表write,b代表bit二进制位,t代表text r 打开只读文件,该文件必须存在 r+ 打开可读可写的文件,该文件...

    程序员互动联盟
  • 收集3:所有文件格式

    A 对象代码库文件 AAM Authorware shocked文件 AAS Authorware shocked包 ABF Adobe二进制屏幕字体 ...

    py3study

扫码关注云+社区

领取腾讯云代金券