<h3 id="时间2016年8月11日-天气晴sunny">时间:2016年8月11日 天气:晴:sunny:</h3>
Author:冬之晓:dizzy_face:
Email: 347916416@qq.com
MyAppearance: MyAppearance
    今天上午，陈博士过来找我，问我学习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的集合，用于创建用户自定义文本小节，它会在连接点与关联页面之间自动生成交叉引用，并且能搜集关联页面中的所有相同类型的小节。第一个参数是一个表述小节类型的唯一标识，第二个参数是一个加了引号的字符串，它用于表述第四个参数放置文本下的小节头，为包含同一个标识的所有条目相关页面，第三个参数将作为一个标题来使用，一些已经预定义的标识：`todo,test,bug,deprecated`。

想想如果使用@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 "" """