gtk-doc: GTK+ API 参考手册框架介绍

**GNOME 代码中的内嵌示文档**

在 GNOME 源码文件中使用注示块来为函数(宏, 信号和属性等)生成文档.

/**
* function_name:
* @par1: 第一个参数的描述, 可以扩展到多行.
* 以便描述参数的详细信息.
* @par2: 第二个参数的描述, 同上.
*
* 这里是对函数的描述, 你可以使用 @parN 来引用第N个参数,
* 这样生成的文档里就会产生一个高度显示的输出. 也可以使用 %constant
* 来注示常量, function_name2() 来表示其它函数, 用 #GtkWidget 来连接
* 到其它描述中(可以是其它任何地方)
*
* Returns: 一个整形数.
*/

块以 '/**' 开始.
每一行以 '*' 开始.

第二行是 函数名, 可以跟上一个 ':' 号. 如果要在内嵌的注示中为信号添加文档, 则使用 class::signal 这样的格式, 如: GtkWidget::notify-child. 为属性添加文档, 则使用 class:property 这样的格式, 如: GtkAlignment:top-padding. 需要注意的是, gtk-doc 希望信号和属性使用连接号(-) 书写, 而不是下划线(_).

函数名接下来一行是参数列表. 如上面的: '@par1' .

参数列表与函数功能描述之间必须有一个空行隔开(不然就会被认为是参数描述的一部分).

接下来的一行 'Returns:' 用来描述函数的返回值(如果有返回值的话)

所有的描述中都可以使用一些特殊字符(它们将会被扩展成为适当的 DocBook 标签):

@name 一个参数.

%name 一个常量.

name() 一个函数, 或者是一个类似函数的宏的参考 (如果这个函数/宏有相应文档的话, 这里将生成一个到相应文档位置的超连接).

#name 一个到其它类型的文档的参考, 如: 结构, 枚举, 联合或宏( 如果有相应文档的话, 这里也将生成 一个超连接)

为了避免问题, 注示中的字符 '<', '>' 和 '&' 都将被转换成为 SGML 的实体 &lt; &gt; 和 &amp;.

也就是说你不能使用 DocBook SGML 标签, 除非你为 gtkdoc-mkdb 指定 --sgml-mode 选项, 使得从注示中生成文档时, 不保留'<', '>' 和 '&', 并认可其中的属于 DocBook 的标记.

如果你要在内嵌注示中使用标记, 你必须避免因为有空行而行成自动分段引起的问题. 如果在前缀 ' *' 之后没有字符了, 这一行将被记为空行. 因此, 你可以在一个类似的空行里加入几个空格来解决决这个问题, 使之成为一个空行, 而不是一分段. 这种情况在示例代码中常遇到, 常常包含这样的空行.

这是一个内嵌文档的例子:

libgnomecanvas-installed-gxy/libgnomecanvas/gnome-canvas.c

/**
* gnome_canvas_item_new:
* @parent: The parent group for the new item.
* @type: The object type of the item.
* @first_arg_name: A list of object argument name/value pairs, NULL-terminated,
* used to configure the item. For example, "fill_color", "black",
* "width_units", 5.0, NULL.
* @Varargs:
*
* Creates a new canvas item with @parent as its parent group. The item is
* created at the top of its parent's stack, and starts up as visible. The item
* is of the specified @type, for example, it can be
* gnome_canvas_rect_get_type(). The list of object arguments/value pairs is
* used to configure the item.
*
* Return value: The newly-created item.
**/
GnomeCanvasItem *
gnome_canvas_item_new (GnomeCanvasGroup *parent, GType type, const gchar *first_arg_name, ...)
{
...
}
</pre>

生成的文档如下: http://developer.gnome.org/doc/API/2.0/libgnomecanvas/GnomeCanvasItem.html#gnome-canvas-item-new

**更多技巧**:

超连接在一些例子中也会变得很糟, 因此, 你可以使用 function(<!-- -->) 来替代 function() 而避免这个函数被转换成一个超连接. 使用字符实体来引用 %, &, < 或 # 这些字符, 如::

if (a < b && verbose)
printf ("bla %s %#x", bla, a);

应该换成::

if (a &lt; b &amp;&amp; verbose)
printf ("bla &percnt;s &percnt;&num;x", bla, a);