编写符号文档
每个符号(函数,宏,结构,枚举,信号及属性)都在各自独立的块中描述。这些块最好放置于接近标识符定义的地方,这样可以容易地让它们保持同步。因此函数通常在C代码中定义,宏和结构及枚举在头文件里定义。
3.3.1. 一般标记
你可以为所有的文档元素加入版本信息,表明何时引入或废弃了某个API。
版本标记
- 始于:
-
描述从哪个版本的代码开始加入了该API。
- 废弃:
-
表明这个函数不应再使用的一段文档。描述文字应向读者介绍新的API。
(FIXME : 稳定性信息)
Example 3-5 一般标记
/** * 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. 函数注释块
请记得:
- 描述返回的对象、列表、字符串等是否应释放内存(freed)/解除引用/释放(released)。
- 描述参数可否为NULL,如果是的话会发生什么。
- 在适当时提及相关的前提条件与后续条件。
Gtk-doc 假定所有以'_'符开头的符号(宏,函数)是私有的并视它们为静态函数。
Also, take a look at GObject Introspection annotation tags: http://live.gnome.org/GObjectIntrospection/Annotations
Example 3-6 函数注释块
/** * function_name: * @par1: 对参数 1 的描述。 * 可超过一行。 * @par2: 对参数 2 的描述 * @...: 一个以 %NULL 终止的 bars 列表 * * 这里是函数描述。您可以用 @par1 引用参数,这样在输出中它们会突出显示。 * 您也可以使用 %constant 代表常量,function_name2() 代表函数,#GtkWidget * 代表指向指向其他声明的链接(可能在其他位置描述)。 * * 返回值: 一个整型值。 * * 始于: 2.2 * 废弃: 2.18: 请转用 other_function()。 */
函数标记
- 返回值:
-
描述返回结果的段落。
- @...:
-
如果函数有变长参数列表,你应当使用这个标记(@Varargs: 由于历史原因确实也管用)。
3.3.3. 属性注释块
Example 3-7 属性注释块
/** * SomeWidget:some-property: * * 这里您可以描述一个属性。 */ g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);
3.3.4. 信号注释块
请记得:
- 描述信号何时发射(emitted)及在其它信号之前还是之后发射。
- 描述应用程序在信号处理函数中能做些什么。
Example 3-8 信号注释块
/** * FooWidget::foobarized: * @widget: 接受信号的窗口部件 * @foo: some foo * @bar: some bar * * ::foobarized 信号在每次有人尝试 foobarize @widget 时发射。 */ foo_signals[FOOBARIZE] = g_signal_new ("foobarize", ...
3.3.5. 结构注释块
Example 3-9 结构注释块
/** * FooWidget: * @bar: some #gboolean * * 这是史上最好的窗口部件。 */ typedef struct _FooWidget { /*< private >*/ GtkWidget parent; /*< public >*/ gboolean bar; } FooWidget;
在你需要隐藏的私有结构字段之前使用/*< private >*/ 。反之使用/*< public >*/.
结构注释块也可以用于GObjects与GObjectClasses。为一个类添加注释块通常是个极好的主意,如果它有vmethod(因为这是怎样制作它的文档的方法)。对于GObject自身而言,你可以使用相关的章节文档,如果对象实例有公共字段,为每个实例结构体单独块注释是非常有用的。缺点是这会为同一名字创建两个索引记录(结构与章节)。
3.3.6. 枚举注释块
Example 3-10 枚举注释块
/** * 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 >*/ 。