编写符号文档

每个符号(函数,宏,结构,枚举,信号及属性)都在各自独立的块中描述。这些块最好放置于接近标识符定义的地方,这样可以容易地让它们保持同步。因此函数通常在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 >*/