qdoc 写法

 Qdoc 注释

Qdoc注释有一些命令， 能够对文档进行组织。

QDoc能识别以下3种类型的命令

主题（topic command）

主题命令确定了文档的元素，例如C++类（class），函数（function），类型（type），或者和所有元素无关的一段文字。

上下文（context command）

上下文命令向QDoc说明了qdoc文件中某个元素和另外的元素怎么样联系，例如前后页链接，同一主题的页组，或者其它链接库，上下文命令还能够获取元素的那些在源代码文件中无法获取到的信息，例如，该元素是否线程安全，是否是一个重载或者覆写函数，是否已被废除，属于哪个module等

 

标记（Makeup command）

标记命令告诉QDoc文档中的文字和图片如何渲染，以及文档的大纲结构。

 

 

主题（topic command）

一个主题命令向QDoc指明源代码中哪一个语法元素要被归档，还有一些主题命令允许您创建没有绑定到任何源代码语法元素的文档页面。当QDoc遍历QDoc注释时,它试图通过首先寻找到一个主题命令来把源代码元素连接到这个注释上。如果没有主题命令， QDoc会连接紧跟在该注释之后的源代码元素。如果不满足上述条件,并且注释中没有其它元素来说明这段注释与源代码无关， 那么该段注释就会被丢弃。

相关的语法元素的名字通常是主题命令唯一的参数字段， 这里要使用完整的名称。有时可以有第二个参数。例如 \page。

\fn 也是一个特例， 它需要加上完整的函数信息， 因此它可能会有多个字段， 但是是一个参数。如果注释中没有 主题命令，qdoc会把这段注释与紧跟其后的代码 联系起来。

主题命令可以出现在注释中的任何位置，但必须独立一行。把主题命令放在第一行是一种很好的做法。如果参数字段跨越几行,确保每一行(除了最后一个)使用一个反斜杠结束。此外,QDoc计数括号,这意味着如果它遇到一个“(“，它会把”)”之前的所有内容作为其参数。

几个主题命令（详见qdoc）

\class 会生成一个以参数名的小写为文件名的独立html页面

\externalpage 给一个url定义别名，这样在其它地方可以使用 \l 去引用

Miscellaneous： 

提供一些作用于文档生成和渲染的一些命令。

\group 用于生成一个列举了所有类的独立的页面，这些类有 \ingroup 元素。

Relating Things：

\headerfile 用于生成一个包含了一个头文件中的全局函数、类型、宏等的页面

\relates 用于把一个全局的元素包含到一个头文件或者类中。 例如， 声明了 \class QChar , 再声明 \relates AElem， 就会在QChar 页面中看到AElem

  \overload 说明函数是重载函数， 参数是重载的函数

\reimp 用于说明一个函数覆写了虚函数。