Kommentare zur Dokumentation
Ein mehrzeiliger Kommentar, der mit einem zusätzlichen »*« beginnt, markiert einen Kommentarblock, der von den Werkzeugen in GTK-Doc verarbeitet wird.
/** * 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.
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).
Beim Dokumentieren von Code beschreiben Sie zwei Aspekte:
- 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.
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.
- Use #Object::signal to refer to a GObject signal.
- Use #Object:property to refer to a GObject property.
- Verwenden Sie #Struct.field, um auf ein Feld innerhalb einer Struktur zu verweisen.
Falls Sie die Sonderzeichen »<«, »>«, »()«, »@«, »%« oder »#« in Ihrer Dokumentation verwenden wollen, ohne dass GTK-Doc diese ändert, können Sie die XML-Entitäten »<«, »>«, »(«, »)«, »@«, »%« und »#« verwenden oder die Zeichen mit einem Backslash »\« maskieren.
DocBook kann mehr als nur verknüpfen. Sie können auch Listen, Tabellen und Beispiele einbauen. Um die Nutzung der DocBook-SGML/XML-Tags innerhalb der Dokumentationskommentare zu aktivieren, übergeben Sie der Variable MKDB_OPTIONS in der Datei Makefile.am die Option --xml-mode oder --sgml-mode.
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).
/** * identifier: * * documentation ... * * # Sub heading # * * more documentation: * - list item 1 * - list item 2 * * Even more docs. */
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.