编写代码文档
GTK-Doc uses source code comment with a special syntax for code documentation. Further it retrieves information about your project structure from other sources. During the next section you will find all information about the syntax of the comments.

文档位置
在过去，多数文档不得不写入驻留在tmpl目录的文件中。这样会出现一些糟糕的情况：其信息常常没有更新，而且文件也倾向于与版本控制系统发生冲突。
为避免上述的问题，我们建议把注释文档放入源代码中去。本手册仅描述此种编写代码文档的方法。
The scanner can handle the majority of C headers fine. In the case of receiving warnings from the scanner that look like a special case, one can hint GTK-Doc to skip over them.

GTK-Doc comment block

#ifndef __GTK_DOC_IGNORE__
/* unparseable code here */
#endif

Limitations
Note, that GTK-Doc's supports #ifndef(__GTK_DOC_IGNORE__) but not #if !defined(__GTK_DOC_IGNORE__) or other combinations.

文档注释
A multiline comment that starts with an additional '*' marks a documentation block that will be processed by the GTK-Doc tools.

GTK-Doc comment block

/**
 * identifier:
 * documentation ...
 */

The 'identifier' is one line with the name of the item the comment is related to. The syntax differs a little depending on the item. (TODO add table showing identifiers)
The 'documentation' block is also different for each symbol type. Symbol types that get parameters such as functions or macros have the parameter description first followed by a blank line (just a '*'). Afterwards follows the detailed description. All lines (outside program listings and CDATA sections) just containing a ' *' (blank-asterisk) are converted to paragraph breaks. If you don't want a paragraph break, change that into ' * ' (blank-asterisk-blank-blank). This is useful in preformatted text (code listings).
When documenting code, describe two aspects:
What it is: The name for a class or function can sometimes be misleading for people coming from a different background.
What it does: Tell about common uses. Put it in relation with the other API.
与纯文本相比，超文本的优势在于可以在文档内部有链接。但为一个链接编写正确的标记可能是件枯燥的差事。GTK-Doc提供了几个有用的简化方法帮你解决这个麻烦。
用function()来指示带有参数的函数或宏。
用@param指示参数。同样也可以指示其它函数的参数，与所描述的对象有关。
用%constant指示常量，比如：%G_TRAVERSE_LEAFS。
用#symbol指示其它符号类型，比如：结构，枚举与不带参数的宏。
Use #Object::signal to refer to a GObject signal.
Use #Object:property to refer to a GObject property.
Use #Struct.field to refer to a field inside a structure and #GObjectClass.foo_bar() to refer to a vmethod.
如果你要在文档里面使用一些特殊的字符'<', '>', '()', '@', '%', or '#' 且不用GTK-Doc来修改它们，你可以相应地用XML 实体 "&lt;", "&gt;", "&lpar;", "&rpar;", "&commat;", "&percnt;" 以及 "&num;"或者用一个反斜线'\'来转义它们。
DocBook can do more than just links. One can also have lists, examples, headings, and images. As of version 1.20, the preferred way is to use a subset of the basic text formatting syntax called Markdown. On older GTK-Doc versions any documentation that includes Markdown will be rendered as is. For example, list items will appear as lines starting with a dash.
While markdown is now preferred one can mix both. One limitation here is that one can use docbook xml within markdown, but markdown within docbook xml is not supported.
In older GTK-Doc releases, if you need support for additional formatting, you would need to enable the usage of docbook XML tags inside doc-comments by putting --xml-mode (or --sgml-mode) in the variable MKDB_OPTIONS inside Makefile.am.

GTK-Doc comment block using Markdown

/**
 * identifier:
 *
 * documentation paragraph ...
 *
 * # Sub Heading #
 *
 * ## Second Sub Heading
 *
 * # Sub Heading With a Link Anchor # {#heading-two}
 *
 * more documentation:
 *
 * - list item 1
 *
 *   Paragraph inside a list item.
 *
 * - list item 2
 *
 * 1. numbered list item
 *
 * 2. another numbered list item
 *
 * Another paragraph. [A Link to the GNOME Website](http://www.gnome.org/)
 *
 * ![an inline image](plot-result.png)
 *
 * [A link to the heading anchor above][heading-two]
 *
 * A C-language example:
 * |[<!-- language="C" -->
 * GtkWidget *label = gtk_label_new ("Gorgeous!");
 * ]|
 */

More examples of what markdown tags are supported can be found in the GTK+ Documentation Markdown Syntax Reference.
如早先所述，GTK-Doc是为编写公共的API而作的。所以你不能够为静态符号编写文档。尽管如此，它也可以很好地为那些符号作注释。这有助于他人理解你的代码。因此我们建议你用普通的注释来注释它们（不使用第一行的第二个'*'号）。如果以后函数须要作为public，你须做的只是在注释块中加入另一个 '*'号并且在区段文件里插入正确的标识符名称。

文档章节
文档的每个章节都包含着关于一个类或模块的信息。要介绍它的组件，你可以编写一节注释块。在内容表格中也可以使用简短的描述。所有的@fields都是可选的。

节注释块

/**
 * SECTION:meepapp
 * @short_description: the application class
 * @title: Meep application
 * @section_id:
 * @see_also: #MeepSettings
 * @stability: Stable
 * @include: meep/app.h
 * @image: application.png
 *
 * The application class handles ...
 */

SECTION:<name> 	 The name links the section documentation to the respective part in the <package>-sections.txt file. The name given here should match the <FILE> tag in the <package>-sections.txt file.
@short_description 	 该节的单行描述，不久将出现在TOC里的链接后和该节页面的顶部。
@title 	 段落的标题在SECTION声明里默认是 <name> 。它可以由@title字段替换。
@section_id 	 替换标题的用途作为一个段落指示器。对于GObjects，<title>用作section_id且对于其它的段落它是<MODULE>-<title>。
@see_also 	 与本节相关的标识符。
@stability 	 An informal description of the stability level this API has. We recommend the use of one of these terms:
Stable - The intention of a Stable interface is to enable arbitrary third parties to develop applications to these interfaces, release them, and have confidence that they will run on all minor releases of the product (after the one in which the interface was introduced, and within the same major release). Even at a major release, incompatible changes are expected to be rare, and to have strong justifications.
Unstable - Unstable interfaces are experimental or transitional. They are typically used to give outside developers early access to new or rapidly changing technology, or to provide an interim solution to a problem where a more general solution is anticipated. No claims are made about either source or binary compatibility from one minor release to the next.
Private - An interface that can be used within the GNOME stack itself, but that is not documented for end-users. Such functions should only be used in specified and documented ways.
Internal - An interface that is internal to a module and does not require end-user documentation. Functions that are undocumented are assumed to be Internal.
@include 	 The #include files to show in the section synopsis (a comma separated list), overriding the global value from the section file or command line. This item is optional.
@image 	 本章节的参考页顶部显示的图像。这常常是某些用于阐释一个类或者图表与其它类之间关系的可视化图示。这个项是可选的。
为避免不必要的重编译，在文档改动后尽可能把段落文档放入C代码中合适的位置。

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

一般标记
你可以为所有的文档元素加入版本信息，表明何时引入或废弃了某个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.

一般标记

/**
 * 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)
{
...

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.

Annotations

/**
 * 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.
 */

函数注释块
请记得：
描述返回的对象、列表、字符串等是否应释放内存(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: 由于历史原因确实也管用）。

属性注释块

属性注释块

/**
 * SomeWidget:some-property:
 *
 * Here you can document a property.
 */
g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);

信号注释块
请记得：
描述信号何时发射(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[FOOBARIZED] =
  g_signal_new ("foobarized",
                ...

结构注释块

结构注释块

/**
 * 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自身而言，你可以使用相关的章节文档，如果对象实例有公共字段，为每个实例结构体单独块注释是非常有用的。缺点是这会为同一名字创建两个索引记录（结构与章节）。

枚举注释块

枚举注释块

/**
 * 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 >*/ 。

Inline program documentation
You can document programs and their commandline interface using inline documentation.

Tags
PROGRAM 	 Defines the start of a program documentation.
@short_description: 	 Defines a short description of the program. (Optional)
@synopsis: 	 Defines the arguments, or list of arguments that the program can take. (Optional)
@see_also: 	 See Also manual page section. (Optional)
@arg: 	 Argument(s) passed to the program and their description. (Optional)
Description: 	 A longer description of the program.
返回值： 	 Specificy what value(s) the program returns. (Optional)

Example of program documentation.

Program documentation block

/**
 * PROGRAM:test-program
 * @short_description: A test program
 * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
 * @see_also: test(1)
 * @--arg1 *arg*: set arg1 to *arg*
 * @--arg2 *arg*: set arg2 to *arg*
 * @-v, --version: Print the version number
 * @-h, --help: Print the help message
 *
 * Long description of program.
 *
 * Returns: Zero on success, non-zero on failure
 */
int main(int argc, char *argv[])
{
	return 0;
}

有用的DocBook标记
这些是在编写代码文档时非常有用处的DocBook标记。
To link to another section in the GTK docs:

<link linkend="glib-Hash-Tables">Hash Tables</link>

The linkend is the SGML/XML id on the top item of the page you want to link to. For most pages this is currently the part ("gtk", "gdk", "glib") and then the page title ("Hash Tables"). For widgets it is just the class name. Spaces and underscores are converted to '-' to conform to SGML/XML.
引用一个外部函数，比如一个标准 C 函数：

<function>...</function>

要包含示例代码：

<example>
  <title>Using a GHashTable.</title>
  <programlisting>
      ...
  </programlisting>
</example>

或类似的，很短的不需要标题的代码段：

<informalexample>
  <programlisting>
  ...
  </programlisting>
</informalexample>

对后者，GTK-Doc 还支持一种缩写方式：|[ ... ]|
要包含符号列表：

<itemizedlist>
  <listitem>
    <para>
      ...
    </para>
  </listitem>
  <listitem>
    <para>
      ...
    </para>
  </listitem>
</itemizedlist>

要包含一条文字中突出显示的注解：

<note>
  <para>
    Make sure you free the data after use.
  </para>
</note>

要引用一个类型：

<type>unsigned char</type>

引用一个外部结构（不是在GTK 文档中描述的）：

<structname>XFontStruct</structname>

要引用一个结构字段：

<structfield>len</structfield>

要引用一个类的名字，你可能会使用：

<classname>GtkWidget</classname>

但是你可能正在使用#GtkWidget（要自动创建一个到GtkWidget 页面的链接－请参阅缩写）。
要强调文本：

<emphasis>This is important</emphasis>

对于文件名，使用：

<filename>/home/user/documents</filename>

要引用键值，使用：

<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>