文档注释
A multiline comment that starts with an additional '*' marks a documentation block that will be processed by the GTK-Doc tools.
/** * 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 实体 "<", ">", "(", ")", "@", "%" 以及 "#"或者用一个反斜线'\'来转义它们。
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.
In older GTK-Doc releases, if you need support for additional formatting, you would need to enable the usage of docbook SGML/XML tags inside doc-comments by putting --xml-mode or --sgml-mode in the variable MKDB_OPTIONS inside Makefile.am.
/** * 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,你须做的只是在注释块中加入另一个 '*'号并且在区段文件里插入正确的标识符名称。