编写符号文档
每个符号(函数,宏,结构,枚举,信号及属性)都在各自独立的块中描述。这些块最好放置于接近标识符定义的地方,这样可以容易地让它们保持同步。因此函数通常在C代码中定义,宏和结构及枚举在头文件里定义。
3.3.1. 一般标记
你可以为所有的文档元素加入版本信息,表明何时引入或废弃了某个API。
- 始于:
-
描述从哪个版本的代码开始加入了该API。
- 废弃:
-
表明这个函数不应再使用的一段文档。描述文字应向读者介绍新的API。
(FIXME : 稳定性信息)
/** * foo_get_bar: * @foo: some foo * * Retrieves @foo's bar. * * Returns: @foo's bar * * Since: 2.6 * Deprecated: 2.12: Use foo_baz_get_bar() instead. */ Bar * foo_get_bar(Foo *foo) { ...
3.3.2. Annotations
Documentation blocks can contain annotation-tags. These tags will be rendered with tooltips describing their meaning. The tags are used by gobject-introspection to generate language bindings. A detailed list of the supported tags can be found on the wiki.
/** * foo_get_bar: (annotation) * @foo: (annotation): some foo * * Retrieves @foo's bar. * * Returns: (annotation): @foo's bar */ ... /** * foo_set_bar_using_the_frobnicator: (annotation) (another annotation) * (and another annotation) * @foo: (annotation) (another annotation): some foo * * Sets bar on @foo. */
3.3.3. 函数注释块
请记得:
- 描述返回的对象、列表、字符串等是否应释放内存(freed)/解除引用/释放(released)。
- 描述参数可否为NULL,如果是的话会发生什么。
- 在适当时提及相关的前提条件与后续条件。
Gtk-doc 假定所有以'_'符开头的符号(宏,函数)是私有的并视它们为静态函数。
/** * function_name: * @par1: description of parameter 1. These can extend over more than * one line. * @par2: description of parameter 2 * @...: a %NULL-terminated list of bars * * The function description goes here. You can use @par1 to refer to parameters * so that they are highlighted in the output. You can also use %constant * for constants, function_name2() for functions and #GtkWidget for links to * other declarations (which may be documented elsewhere). * * Returns: an integer. * * Since: 2.2 * Deprecated: 2.18: Use other_function() instead. */
- 返回值:
-
描述返回结果的段落。
- @...:
-
如果函数有变长参数列表,你应当使用这个标记(@Varargs: 由于历史原因确实也管用)。
3.3.4. 属性注释块
/** * SomeWidget:some-property: * * Here you can document a property. */ g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);
3.3.5. 信号注释块
请记得:
- 描述信号何时发射(emitted)及在其它信号之前还是之后发射。
- 描述应用程序在信号处理函数中能做些什么。
/** * FooWidget::foobarized: * @widget: the widget that received the signal * @foo: some foo * @bar: some bar * * The ::foobarized signal is emitted each time someone tries to foobarize @widget. */ foo_signals[FOOBARIZE] = g_signal_new ("foobarize", ...
3.3.6. 结构注释块
/** * FooWidget: * @bar: some #gboolean * * This is the best widget, ever. */ typedef struct _FooWidget { /*< private >*/ GtkWidget parent; /*< public >*/ gboolean bar; } FooWidget;
在你需要隐藏的私有结构字段之前使用/*< private >*/ 。反之使用/*< public >*/.
结构注释块也可以用于GObjects与GObjectClasses。为一个类添加注释块通常是个极好的主意,如果它有vmethod(因为这是怎样制作它的文档的方法)。对于GObject自身而言,你可以使用相关的章节文档,如果对象实例有公共字段,为每个实例结构体单独块注释是非常有用的。缺点是这会为同一名字创建两个索引记录(结构与章节)。
3.3.7. 枚举注释块
/** * Something: * @SOMETHING_FOO: something foo * @SOMETHING_BAR: something bar * * Enum values used for the thing, to specify the thing. */ typedef enum { SOMETHING_FOO, SOMETHING_BAR, /*< private >*/ SOMETHING_COUNT } Something;
在你要隐藏的枚举数值前使用/*< private >*/。反之使用/*< public >*/ 。