文档注释

A multiline comment that starts with an additional '*' marks a documentation block that will be processed by the GTK-Doc tools.

Example 3-2GTK-Doc comment block
/**
 * identifier:
 * documentation ...
 */

          

The 'identifier' is one line with the name of the item the comment is related to. The syntax differs a little depending on the item. (TODO add table showing identifiers)

The 'documentation' block is also different for each symbol type. Symbol types that get parameters such as functions or macros have the parameter description first followed by a blank line (just a '*'). Afterwards follows the detailed description. All lines (outside program listings and CDATA sections) just containing a ' *' (blank-asterisk) are converted to paragraph breaks. If you don't want a paragraph break, change that into ' * ' (blank-asterisk-blank-blank). This is useful in preformatted text (code listings).

When documenting code, describe two aspects:

  • What it is: The name for a class or function can sometimes be misleading for people coming from a different background.
  • What it does: Tell about common uses. Put it in relation with the other API.

与纯文本相比,超文本的优势在于可以在文档内部有链接。但为一个链接编写正确的标记可能是件枯燥的差事。GTK-Doc提供了几个有用的简化方法帮你解决这个麻烦。

  • 用function()来指示带有参数的函数或宏。
  • 用@param指示参数。同样也可以指示其它函数的参数,与所描述的对象有关。
  • 用%constant指示常量,比如:%G_TRAVERSE_LEAFS。
  • 用#symbol指示其它符号类型,比如:结构,枚举与不带参数的宏。
  • Use #Object::signal to refer to a GObject signal.
  • Use #Object:property to refer to a GObject property.
  • 用#Struct.field指示结构体的字段。

如果你要在文档里面使用一些特殊的字符'<', '>', '()', '@', '%', or '#' 且不用GTK-Doc来修改它们,你可以相应地用XML 实体 "&lt;", "&gt;", "&lpar;", "&rpar;", "&commat;", "&percnt;" 以及 "&num;"或者用一个反斜线'\'来转义它们。

DocBook可以做比链接多得多的事情。你可以有列表,表格和示例。要在doc-comments中激活docbook SGML/XML标识的使用,你得往Makefile.am文件中的变量MKDB_OPTIONS上加入--xml-mode--sgml-mode选项。

从 GTK-Doc-1.18 版本开始,该工具支持 markdown 标记语言 的一个子集。可以用它定义小标题和简单的项目列表。在较早的 GTK-Doc 版本中,内容会原样渲染(列表项会显示在一行,以短划线隔开)。

Example 3-3使用markdown进行GTK-Doc块注释
/**
 * 标识符:
 *
 * 文档内容 ...
 *
 * # 小标题 #
 *
 * 更多文档:
 * - 列表项1
 * - 列表项2
 *
 * 其余更多文档。
 */

          

如早先所述,GTK-Doc是为编写公共的API而作的。所以你不能够为静态符号编写文档。尽管如此,它也可以很好地为那些符号作注释。这有助于他人理解你的代码。因此我们建议你用普通的注释来注释它们(不使用第一行的第二个'*'号)。如果以后函数须要作为public,你须做的只是在注释块中加入另一个 '*'号并且在区段文件里插入正确的标识符名称。