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.
  • Use #Struct.field to refer to a field inside a structure and #GObjectClass.foo_bar() to refer to a 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 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.

Beispiel 3-3GTK-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.

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.