编写符号文档

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

Example 3-6Annotations
/**
 * 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 假定所有以'_'符开头的符号(宏,函数)是私有的并视它们为静态函数。

Example 3-7函数注释块
/**
 * 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. 属性注释块

Example 3-8属性注释块
/**
 * SomeWidget:some-property:
 *
 * Here you can document a property.
 */
g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);

3.3.5. 信号注释块

请记得:

  • 描述信号何时发射(emitted)及在其它信号之前还是之后发射。
  • 描述应用程序在信号处理函数中能做些什么。

Example 3-9信号注释块
/**
 * 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. 结构注释块

Example 3-10结构注释块
/**
 * 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. 枚举注释块

Example 3-11枚举注释块
/**
 * 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 >*/