Documentation comments
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.
One advantage of hyper-text over plain-text is the ability to have links in the document. Writing the correct markup for a link can be tedious though. GTK-Doc comes to help by providing several useful abbreviations.
- Use function() to refer to functions or macros which take arguments.
- Use @param to refer to parameters. Also use this when referring to parameters of other functions, related to the one being described.
- Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS.
- Use #symbol to refer to other types of symbol, e.g. structs and enums and macros which don't take arguments.
- 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.
If you need to use the special characters '<', '>', '()', '@', '%', or '#' in your documentation without GTK-Doc changing them you can use the XML entities "<", ">", "(", ")", "@", "%" and "#" respectively or escape them with a backslash '\'.
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.
/**
* 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/)
*
* 
*
* [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.
As already mentioned earlier GTK-Doc is for documenting public API. Thus one cannot write documentation for static symbols. Nevertheless it is good to comment those symbols too. This helps other to understand you code. Therefore we recommend to comment these using normal comments (without the 2nd '*' in the first line). If later the function needs to be made public, all one needs to do is to add another '*' in the comment block and insert the symbol name at the right place inside the sections file.