Kommentare zur Dokumentation

Ein mehrzeiliger Kommentar, der mit einem zusätzlichen »*« beginnt, markiert einen Kommentarblock, der von den Werkzeugen in GTK-Doc verarbeitet wird.

Beispiel 3-2GTK-Doc-Kommentarblock
/**
 * identifier:
 * documentation ...
 */

Der »identifier« ist eine Zeile mit dem Namen des Objekts, auf das sich der Kommentar bezieht. Die Syntax kann abhängig von der Art des Objekts variieren.

Der Block »documentation« ist ebenfalls für jeden Symboltyp unterschiedlich. Symboltypen mit Parametern wie Funktionen oder Makros haben eine Parameterbeschreibung, auf die eine leere Zeile folgt (keine echte Leerzeile, sondern ein »*«). Danach folgt eine detaillierte Beschreibung. Alle Zeilen (außerhalb von Programmlistings und CDATA-Abschnitten), die nur ein » *« (Leerzeichen-Asterisk) enthalten, werden in Absatzumbrüche umgewandelt. Falls Sie keinen Absatzumbruch wünschen, verwenden Sie stattdessen ein » * «, d.h. setzen Sie ein Leerzeichen jeweils davor und dahinter. Dies ist in vorformatiertem Text nützlich (Code-Auflistungen).

Beim Dokumentieren von Code beschreiben Sie zwei Aspekte:

  • Was es ist: Der Name für eine Klasse oder Funktion kann manchmal Irre führend sein für Personen, die einen anderen Hintergrund haben.
  • Was es ist: Berichtet über normale Anwendungsfälle. Stellen Sie es ins Verhältnis mit der anderen API.

Ein Vorteil von Hypertext gegenüber Klartext ist die Möglichkeit, Verknüpfungen im Dokument zu verwenden. Das Schreiben eines korrekten Markups für eine solche Verknüpfung kann allerdings langatmig sein, deshalb stellt GTK-Doc eine Reihe von praktischen Abkürzungen bereit.

  • Verwenden Sie function(), um einen Bezug zu Funktionen oder Makros herzustellen, die Argumente akzeptieren.
  • Verwenden Sie @param, um einen Bezug zu Parametern herzustellen. Verwenden Sie dies auch, wenn es um einen Bezug zu Parametern anderer Funktionen geht, bezogen auf jene, die Sie gerade beschreiben.
  • Benutzen Sie %constant, um einen Bezug auf eine Konstante herzustellen, z.B. %G_TRAVERSE_LEAFS.
  • Verwenden Sie #symbol, um auf andere Symboltypen zu verweisen, z.B. »structs« und »enums« und Makros, die keine Argumente benötigen.
  • Verwenden Sie #Object::signal, um auf ein GObject-Signal zu verweisen
  • Verwenden Sie #Object:property, um auf eine GObject-Eigenschaft zu verweisen.
  • Verwenden Sie #Struct.field, um auf ein Feld innerhalb einer Struktur zu verweisen und #GObjectClass.foo_bar() für eine vmethod.

Falls Sie die Sonderzeichen »<«, »>«, »()«, »@«, »%« oder »#« in Ihrer Dokumentation verwenden wollen, ohne dass GTK-Doc diese ändert, können Sie die XML-Entitäten »&lt;«, »&gt;«, »&lpar;«, »&rpar;«, »&commat;«, »&percnt;« und »&num;« verwenden oder die Zeichen mit einem Backslash »\« maskieren.

DocBook kann mehr als nur Verweise zu erzeugen. Sie können Listen, Beispiele, Überschriften und Bilder einfügen. In Version 1.20 ist der bevorzugte Weg, ein Subset grundlegender Textformatierungssyntax namens Markdown zu verwenden. In älteren Versionen von GTK-Doc wird jede Dokumentation, die Markdown enthält, unverändert gerendert. Zum Beispiel erscheinen Listenobjekte als Zeilen, die mit einem Gedankenstrich beginnen.

Wenngleich Markdown bevorzugt wird, können Sie beide Formate mischen. Eine Einschränkung ist jedoch, dass Sie DocBook XML innerhalb von Markdown verwenden können, während Markdown in DocBook XML nicht unterstützt wird.

Um die Nutzung der DocBook-XML-Markierungen innerhalb der Dokumentationskommentare zu aktivieren, übergeben Sie der Variable MKDB_OPTIONS in der Datei Makefile.am die Option --xml-mode (oder --sgml-mode).

Beispiel 3-3GTK-Doc-Kommentarblock in Markdown-Syntax
/**
 * 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!");
 * ]|
 */

Weitere Beispiele zu den unterstützten Markdown-Formatierungen finden Sie in der GTK+ Documentation Markdown Syntax Reference.

Wie an früherer Stelle bereits erwähnt, ist GTK-Doc für das Dokumentieren der öffentlichen API gedacht. Daher kann man keine Dokumentation für statische Symbole schreiben. Nichtsdestotrotz ist es jedoch gut, diese Symbole trotzdem zu dokumentieren. Dies hilft anderen, Ihren Code besser zu verstehen. Deswegen empfehlen wir, hierfür normale Kommentare zu verwenden, ohne das zweite »*« in der ersten Zeile. Falls später die Funktion veröffentlicht werden soll, ist es lediglich nötig, im Kommentarblock ein zweites »*« hinzuzufügen und den Symbolnamen an der richtigen Stelle in die Abschnittsdatei einzubauen.