编写符号文档

每个符号(函数,宏,结构,枚举,信号及属性)都在各自独立的块中描述。这些块最好放置于接近标识符定义的地方,这样可以容易地让它们保持同步。因此函数通常在C代码中定义,宏和结构及枚举在头文件里定义。

3.3.1. 一般标记

你可以为所有的文档元素加入版本信息,表明何时引入或废弃了某个API。

版本标记
始于:

描述从哪个版本的代码开始加入了该API。

废弃:

表明这个函数不应再使用的一段文档。描述文字应向读者介绍新的API。

You can also add stability information to all documentation elements to indicate whether API stability is guaranteed for them for all future minor releases of the project.

The default stability level for all documentation elements can be set by passing the --default-stability argument to gtkdoc-mkdb with one of the values below.

Stability Tags
Stability: Stable

Mark the element as stable. This is for public APIs which are guaranteed to remain stable for all future minor releases of the project.

Stability: Unstable

Mark the element as unstable. This is for public APIs which are released as a preview before being stabilised.

Stability: Private

Mark the element as private. This is for interfaces which can be used by tightly coupled modules, but not by arbitrary third parties.

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 {
  GtkWidget parent_instance;

  gboolean bar;
} FooWidget;

在你需要隐藏的私有结构字段之前使用/*< private >*/ 。反之使用/*< public >*/.

If the first field is "g_iface", "parent_instance" or "parent_class" it will be considered private automatically and doesn't need to be mentioned in the comment block.

结构注释块也可以用于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 >*/