Documentation comments

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

Exempel 3-2GTK-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.

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.

If you need to use the special characters '<', '>', '()', '@', '%', or '#' in your documentation without GTK-Doc changing them you can use the XML entities "&lt;", "&gt;", "&lpar;", "&rpar;", "&commat;", "&percnt;" and "&num;" respectively or escape them with a backslash '\'.

DocBook can do more than just links. One can also have lists, tables and examples. To enable the usage of docbook SGML/XML tags inside doc-comments you need to have --xml-mode or --sgml-mode in the variable MKDB_OPTIONS inside Makefile.am.

Since GTK-Doc-1.18 the tool supports a subset or the markdown language. One can use it for sub-headings and simple itemized lists. On older GTK-Doc versions the content will be rendered as it (the list items will appear in one line separated by dashes).

Exempel 3-3GTK-Doc comment block using markdown
/**
 * identifier:
 *
 * documentation ...
 *
 * # Sub heading #
 *
 * more documentation:
 * - list item 1
 * - list item 2
 *
 * Even more docs.
 */

          

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.