学习Lua语言进度
<h3 id="时间2016年8月11日-天气晴sunny">时间:2016年8月11日 天气:晴:sunny:</h3>
Author:冬之晓:dizzy_face:
Email: 347916416@qq.com
MyAppearance: ![我的头像 MyAppearance](https://github.com/Dongzhixiao/PictureCache/raw/master/MyPicture.JPG)
今天上午,陈博士过来找我,问我学习Lua语言学习的进度。说了惭愧,我最近一 直在看C++那一块的源代码,而且发现代码里面的注释块做的不好,因此研究了一下文档 的标准写法。并且在读代码的同时将里面的注释顺便改成标准格式,但是这样就耽误了Lu a语言的学习进度。为了赶上下来的任务,我需要每天抽出一段时间来进行Lua语言的学习 了。但是文档的内容还没有完全学完,因此这几天晚上继续文档学习,完成之后会研究一 段Lua语言。
小节指示命令
小节指示命令都比较常用,要多多学习!
- @attention { attention text }
开始一个可输入需要处理信息的段落,次段落将会缩排,段落的文本不会指定一个内部结构,所有视觉增强的命令可以放置到该段落中,多个相邻的@attention
命令将被组合到一个单独的段落中,当遇到一个空白行或者是其他的小节命令,那么@attention
将终止。
- @author { list of authors }
开始一个可输入一个或者多个作者名的段落,此段落将会缩排,段落的文本不会指定一个内部结构,所有视觉增强命令可以放置到该段落中,多个相邻的@author
命令将被组合到一个单独的段落中,每个作者描述都将开启一个新行,另外一个 @author
命令可能会有若干个作者,当遇到一个空白行或者是其他的小节命令,那么@author
将终止。例如:
/*!
* @brief Pretty nice class.
* @details This class is used to demonstrate a number of section commands.
* @author John Doe
* @author Jan Doe
* @version 4.1a * date 1990-2011
* @pre First initialize the system.
* @bug Not all memory is freed when deleting an object of this class.
* @warning Improper use can crash your application
* @copyright GNU Public License.
*/
class SomeNiceClass {};
- @authors { list of authors }
同@author
等价
- @brief { brief description }
开始一个作为简明描述的段落,在文档页的起始部分可使用类和文档的简明描述的列表,可在细节描述的前端和成员声明处放置类成员和文档成员的简明描述。一个简明描述可能需要若干行(尽管建议它保持简明的风格)。当遇到一个空白行或者是其他的小节命令,那么简明描述将终止。如果出现多个@brief
命令,那么它们将被组合在一起。查看命令@authhor
的例子。等同于命令@short
- @bug { bug description }
开始一个可报告一个或多个bug的段落,此段落将会缩排,段落的文本不会指定一个内部结构,所有视觉增强命令可以放置到该段落中,多个相邻的@bug
命令将被组合到一个单独的段落中,每个bug都将开启一个新行,另外一个 @bug
命令可能会有若干个bug,当遇到一个空白行或者是其他的小节命令,那么@bug
将终止。查看命令@authhor
的例子。
- @cond [(section-label)]
开始一个带条件的小节,使用命令@endcond
来终止该小节,通常在其他的注释块中可查找到@endcond
。此对命令的目的是,(条件化)在处理中将一部分文档排除。
小节将包含在命令@cond
和@endcond
之间,并将小节的标号加入到配置选项ENABLED_SECTIONS
中,如果标号被忽略,该小节也将在处理中被无条件忽略。
在注释块中的条件小节,可使用一个@if...@endif
块。
条件小节能被嵌套,在这种情况下,如果它和嵌套的小节都包含在其中,那么只有被嵌套的小节才会显示。例如:
/** An interface */
class Intf
{
public:
/** A method */
virtual void func() = 0;
/// @cond TEST
/** A method used for testing */
virtual void test() = 0;
/// @endcond
};
/// @cond DEV
/*
* The implementation of the interface
*/
class Implementation : public Intf
{
public:
void func();
/// @cond TEST
void test();
/// @endcond
/// @cond
/** This method is obsolete and does
* not show up in the documentation.
*/
void obsolete();
/// @endcond
};
/// @endcond
- @copyright { copyright description }
开始描述一个实体的版权的段落,这个段落收到约束,这个段落的内容没有特殊的内部结构。查看命令@authhor
的例子。
- @date { date description }
开始一个可可输入一个或多个日期的段落,此段落将会缩排,段落的文本不会指定一个内部结构,所有视觉增强命令可以放置到该段落中,多个相邻的@date
命令将被组合到一个单独的段落中,每个date都将开启一个新行,另外一个 @date
命令可能会有若干个date,当遇到一个空白行或者是其他的小节命令,那么@date
将终止。查看命令@authhor
的例子。
- @deprecated { description }
开始一个指示文档块是否弃用的段落,可用于描述替代方法,预定生命周期等
- @details { detailed description }
如同@brief
开始一个简明描述,@details
将开始一个细节描述,你也可以开始一个新段落(加入空白行),而无需加入命令@details
。
- @else
开始一个条件小节,如果前一个条件小节无效。前一个小节可使用命令@if,@ifnot,@elseif
开始。
- @elseif (section-label)
开始一个条件小节,如果前一个条件小节无效。当条件小节默认为无效时,你必须放置该命令的section-label
到配置标记ENABLED_SECTIONS
中使得命令@elseif
有效。条件块可以嵌套,如果所有嵌套的条件都有效,那么也只有做内层的嵌套小节才会被读取。
- @endcond
结束一个由@cond
开始的条件小节。
- @endif
结束一个由@if或@ifnot
开始的条件小节,每个@if或@ifnot
只能一一对应匹配之后的@endif
。
- @exception
{ exception description }
为一个名字为<exception-object>
异常对象而开始一个描述,其次是此异常的描述。不会去检查是否存在这个异常对象。段落的文本不会指定一个内部结构,所有视觉增强的命令可以放置到该段落中,多个相邻的@exception
命令将被组合到一个单独的段落中,每个参数的描述都将开启一个新行,当遇到一个空白行或者是其他的小节命令,那么@exception
将终止。
与@exception
一样。
- @if (section-label)
开始一个条件化的文档小节,并使用一个匹配的命令@endif
结束。当条件小节默认为无效时,你必须放置该命令的section-label
到配置标记ENABLED_SECTIONS
中使得命令@if
有效。条件块可以嵌套,如果所有嵌套的条件都有效,那么也只有做内层的嵌套小节才会被读取。例如:
/*! Unconditionally shown documentation.
* if Cond1
* Only included if Cond1 is set.
* endif
* if Cond2
* Only included if Cond2 is set.
* if Cond3
* Only included if Cond2 and Cond3 are set.
* endif
* More text.
* endif
* Unconditional text.
*/
如果你在alias中使用了条件命令,如果在两种语言中文档化一个类,你可以这样使用:
/*! english
* This is English.
* endenglish
* dutch
* Dit is Nederlands.
* enddutch
*/
class Example
{
};
一下是配置文档中的alias:
ALIASES = "english=if english"
"endenglish=endif"
"dutch=if dutch"
"enddutch=endif"
那么ENABLED_SECTIONS
即可有效english也可有效dutch
- @ifnot (section-label)
开始一个条件化的文档小节,并使用一个匹配的命令@endif
结束。当条件小节默认为有效时,你必须放置该命令的section-label
到配置标记ENABLED_SECTIONS
中使得命令@ifnot
无效。
- @invariant { description of invariant }
开始一个可描述不变式的段落,此段落将会缩排,段落的文本不会指定一个内部结构,所有视觉增强的命令可以放置到该段落中,多个相邻的@invariant
命令将被组合到一个单独的段落中,每个invariant描述都将开启一个新行,另外一个@invariant
命令可能会有若干个不变式,当遇到一个空白行或者是其他的小节命令,那么@exception
将终止。
- @note { text }
开始一个输入提示的段落,此段落将会缩排,段落的文本不会指定一个内部结构,所有视觉增强的命令可以放置到该段落中,多个相邻的@note
命令将被组合到一个单独的段落中,每个note描述都将开启一个新行,另外一个@note
命令可能会有若干个提示,当遇到一个空白行或者是其他的小节命令,那么@note
将终止。查看@par
命令的例子。
- @par [(paragraph title)] { paragraph }
如果一个段落标题已经给定,此命令将开始一个用户自定义的段头。段头将会占用一行,命令后的段头将会缩排。
如果段落标题未给出,此命令将开始一个新段落,也可插入其他段落命令(如@param或@warning)来终止该命令。
段落的文本不会指定一个内部结构,所有视觉增强的命令可以放置到该段落中,当遇到一个空白行或者是其他的小节命令,那么@par
将终止。例如:
/*! @class Par_Test
* Normal text.
*
* @par User defined paragraph:
* Contents of the paragraph.
*
* @par
* New paragraph under the same heading.
*
* @note
* This note consists of two paragraphs.
* This is the first paragraph.
*
* @par
* And this is the second paragraph.
*
* More normal text.
*/
class Par_Test {};
- @param [(dir)]
{ parameter description }
为一个名字为<parameter-name>
函数参数开始一个参数描述,将会去检查是否存在。如果在函数声明或定义中,该参数(或其他参数)的文档丢失或未出现,将会给出一个警告。
@param
命令有一个可选属性,能指定参数的方向属性,可为into或out
,这有一个例子:
/*! * Copies bytes from a source memory area to a destination memory area,
* where both areas may not overlap.
* @param[out] dest The memory area to copy to.
* @param[in] src The memory area to copy from.
* @param[in] n The number of bytes to copy
*/void
memcpy(void *dest, const void *src, size_t n);
如果参数既可以输入也可输出,则使用[in,out]指定方向属性,段落的文本不会指定一个内部结构,所有视觉增强的命令可以放置到该段落中,多个相邻的@param
命令将被组合到一个单独的段落中,每个参数描述都将开启一个新行,当遇到一个空白行或者是其他的小节命令,那么@param
将终止。
- @parblock
不像那些评论单一段落的参数( @par, @param 和 @warning),@parblock可以作为一个跨越多行段落描述的命令,并且以endparblock
结束。例如:
/** Example of a param command with a description consisting of two paragraphs
* param p
* parblock
* First paragraph of the param description.
*
* Second paragraph of the param description.
* endparblock
* Rest of the comment block continues.
*/
- @endparblock
结束一个以@parblock
开头的段落块。
- @tparam
{ description }
为一个名字为<template-parameter-name>
类或函数模板参数开始一个模板参数描述,等同于@cmdparam
- @post { description of the postcondition }
开始一个可描述的后置条件的段落,此段落将会缩排,段落的文本不会指定一个内部结构,所有视觉增强的命令可以放置到该段落中,多个相邻的@post
命令将被组合到一个单独的段落中,每个后置描述都将开启一个新行,另外一个@post
命令可能会有若干个提示,当遇到一个空白行或者是其他的小节命令,那么@post
将终止。
- @pre { description of the precondition }
开始一个可描述的前置条件的段落,此段落将会缩排,段落的文本不会指定一个内部结构,所有视觉增强的命令可以放置到该段落中,多个相邻的@pre
命令将被组合到一个单独的段落中,每个前置条件描述都将开启一个新行,另外一个@pre
命令可能会有若干个提示,当遇到一个空白行或者是其他的小节命令,那么@pre
将终止。
- @remark { remark text }
开始一个可输入一个或多个备注的段落,此段落将会缩排,段落的文本不会指定一个内部结构,所有视觉增强的命令可以放置到该段落中,多个相邻的@remark
命令将被组合到一个单独的段落中,每个备注都将开启一个新行,另外一个@remark
命令可能会有若干个提示,当遇到一个空白行或者是其他的小节命令,那么@remark
将终止。
- @remarks { remark text }
同@remark
。
- @result { description of the result value }
同@return
。
- @return { description of the return value }
开始一个可输入一个或多个备注的段落,此段落将会缩排,段落的文本不会指定一个内部结构,所有视觉增强的命令可以放置到该段落中,当遇到一个空白行或者是其他的小节命令,那么@remark
将终止。参考@fn
命令中的例子。
- @returns { description of the return value }
同@return
。
- @retval
{ description }
为一个名字为<return value>
函数开始一个返回值的描述,段落的文本不会指定一个内部结构,所有视觉增强的命令可以放置到该段落中,多个相邻的@retval
命令将被组合到一个单独的段落中,每个备注都将开启一个新行,当遇到一个空白行或者是其他的小节命令,那么@retval
将终止。
- @sa { references }
为指定的类、函数、方法、变量、文档、URL的一个或多个交叉引用开始一个段落,使用::或者#
作为类和它的一个成员的引用连接符来组合上述两个名称。在方法名称之后包含一个带括号的参数类型列表,用于若干个重载方法或者构造器的选择。
- @see { references }
为了兼容JavaDoc,等同于@sa
。
- @short { short description }
同@brief
。
- @since { text }
用于指定一个有效的版本和时间,@since
之后的段落不会指定一个内部结构,所有视觉增强的命令可以放置到该段落中,当遇到一个空白行或者是其他的小节命令,那么@since
将终止。
- @test { paragraph describing a test case }
开始一个可描述的测试用例的段落,此描述会添加这个测试用例到一个单独的测试列表中,而这两种描述将可交叉引用。在测试列表中的每一个测试用例的前端,都还有一个指明它出处的头。
- @throw
{ exception description }
同@exception
。
- @throws
{ exception description }
同@throw
。
- @todo { paragraph describing what is to be done }
开始一个可描述的todo条目的段落,此描述会添加这个条目到一个单独的todo列表中,而这两种描述将可交叉引用。在测试列表中的每一个测试用例的前端,都还有一个指明它出处的头。
- @version { version number }
开始一个可可输入一个或多个版本字符串的段落,此段落将会缩排,段落的文本不会指定一个内部结构,所有视觉增强命令可以放置到该段落中,多个相邻的@version
命令将被组合到一个单独的段落中,每个版本描述将开启一个新行,另外一个 @version
命令可能会有若干个版本字符串,当遇到一个空白行或者是其他的小节命令,那么@version
将终止。查看命令@authhor
的例子。
- @warning { warning message }
开始一个可可输入一个或多个警告信息的段落,此段落将会缩排,段落的文本不会指定一个内部结构,所有视觉增强命令可以放置到该段落中,多个相邻的@warning
命令将被组合到一个单独的段落中,每个版本描述将开启一个新行,另外一个 @warning
命令可能会有若干个警告,当遇到一个空白行或者是其他的小节命令,那么@warning
将终止。查看命令@authhor
的例子。
- @xrefitem
"(heading)" "(list title)" { text }
此命令是一个类似于@todo,@bug
的集合,用于创建用户自定义文本小节,它会在连接点与关联页面之间自动生成交叉引用,并且能搜集关联页面中的所有相同类型的小节。第一个参数
想想如果使用@xrefitem
命令和它运行后的结果,如果只考虑todo列表,它看上去更像是一个alias:
xrefitem todo "Todo" "Todo List"
为每个小节都将重复该命令的前三个参数,这使得它非常易错,该命令也可用于合并配置文档中的ALIAES
选项,如果定义一个新命令@reminder
,可添加一下内容到配置文档:
ALIASES += "reminder=xrefitem reminders "Reminder" "Reminders""
注意:命令中第二和第三参数使用转义引号。
万一参数”(heading)”是一个空字符串则没有heading生成。当和@page
命令联合使用时这非常有用。例如:
/** @page my_errors My Errors
* @brief Errors page
*
* Errors page contents.
*/
/** error ERROR 101: in case a file can not be opened.
Check about file system read/write access. */
#define MY_ERR_CANNOT_OPEN_FILE 101
/** error ERROR 102: in case a file can not be closed.
Check about file system read/write access. */
#define MY_ERR_CANNOT_CLOSE_FILE 102
里面的@error
定义为:
ALIASES += "error=xrefitem my_errors "" """