Dokumentieren des Codes
GTK-Doc benutzt Quellcode-Kommentare mit einer speziellen Syntax für Code-Dokumentation. Weiterhin werden Informationen über Ihre Projektstruktur aus anderen Quellen geholt. Im nächsten Abschnitt finden Sie umfassende Informationen über die Syntax der Kommentare.

Platzierung der Dokumentation
In der Vergangenheit wurde die Dokumentation oft in Dateien gespeichert, die im Ordner tmpl liegen. Das hat den Nachteil, dass die Informationen oft nicht aktualisiert wurden und die Datei tendenziell Konflikte mit Versionsverwaltungssystemen verursachen kann.
Um die bereits genannten Probleme zu vermeiden, empfehlen wir, die Dokumentation innerhalb der Quellen zu halten. In diesem Handbuch wird ausschließlich dieser Weg des Dokumentierens des Quellcodes beschrieben.
Der Scanner kann mit den meisten C-Kopfdateien umgehen. Im Falle von Warnungen des Scanners, die wie ein Spezialfall aussehen, kann man GTK-Doc anweisen diese zu überspringen.

GTK-Doc-Kommentarblock

#ifndef __GTK_DOC_IGNORE__
/* unparseable code here */
#endif

Einschränkungen
Beachten Sie, dass GTK-Doc zwar #ifndef(__GTK_DOC_IGNORE__) unterstützt, aber nicht #if !defined(__GTK_DOC_IGNORE__) oder andere Kombinationen.

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

GTK-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).

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

Dokumentieren von Abschnitten
Jeder Abschnitt der Dokumentation enthält Informationen über eine Klasse oder ein Modul. Um eine Komponente hinzuzufügen, können Sie einen Abschnittsblock schreiben. Die Kurzbeschreibung wird auch im Inhaltsverzeichnis verwendet. Alle @-Felder sind optional.

Abschnitts-Kommentarblock

/**
 * SECTION:meepapp
 * @short_description: the application class
 * @title: Meep application
 * @section_id:
 * @see_also: #MeepSettings
 * @stability: Stable
 * @include: meep/app.h
 * @image: application.png
 *
 * The application class handles ...
 */

SECTION:<name> 	 Der Name verweist auf die Abschnittsdokumentation des entsprechenden Teils der Datei <package>-sections.txt. Der hier angegebene Name sollte der Markierung <FILE> in der Datei <package>-sections.txt entsprechen.
@short_description 	 Eine einzeilige Beschreibung des Abschnitts, die später hinter den Verweisen im Inhaltsverzeichnis und oben in der Abschnittsseite erscheint.
@title 	 Der Abschnittstitel in der SECTION-Deklaration, Vorgabe ist <name>. Er kann im Feld @title überschrieben werden.
@section_id 	 Überschreibt den Einsatz von Titeln als Abschnitts-Bezeichner. Für GObjects wird der <Titel> als section_id verwendet and für andere Abschnitte <MODUL>-<Titel>.
@see_also 	 Eine Liste von Symbolen, welche sich auf diesen Abschnitt beziehen.
@stability 	 Eine informelle Beschreibung der Stabilitätsstufe dieser API. Wir empfehlen dafür einen der folgenden Begriffe:
Stabil - Die Absicht einer stabilen Schnittstelle ist es beliebigen Dritten es zu ermöglichen Anwendungen zu diesen Schnittstellen zu entwickeln, diese freizugeben und sich darauf verlassen zu können, dass diese mit allen Unterversionen des Produkts laufen (nach derjenigen, wo die Schnittstelle eingeführt wurde, und innerhalb der gleichen Hauptversion). Selbst bei einer Hauptversion kann man nicht von inkompatiblen Änderungen ausgehen, abgesehen von stark berechtigten.
Instabil - Instabile Schnittstellen sind experimentell oder vorübergehend. Sie werden typischerweise verwendet, um außenstehenden Entwicklern frühen Zugang zu neuen oder sich schnell ändernder Technologie zu geben, oder um eine Übergangslösung für ein Problem zu liefern, für das eine allgemeinere Lösung erwartet wird. Es werden keine Garantien zu Quell- oder Binärkompatibilität von einer minor-Freigabe zur nächsten gegeben.
Privat - Eine Schnittstelle, die im GNOME-Stack selbst verwendet werden kann, aber nicht für Endanwender dokumentiert ist. Solche Funktionen sollten nur auf spezifizierte und dokumentierte Weisen verwendet werden.
Intern - Eine Schnittstelle, die für ein Modul intern ist und keine Endanwender-Dokumentation erfordert. Undokumentierte Funktionen werden als intern angesehen.
@include 	 Die #include -Dateien werden im Abschnitt Zusammenfassung angezeigt (eine durch Kommata getrennte Liste). Der globale Wert aus der Abschnittsdatei oder von der Befehlszeile wird überschrieben. Dieser Punkt ist optional.
@image 	 Das Bild, das am Beginn einer Referenzseite für diesen Abschnitt angezeigt wird. Meist wird es eine Art Diagramm für visuelle Erscheinungsbild einer Klasse oder ein Diagramm sein, das die Beziehungen zu anderen Klassen darstellt. Dieses Objekt ist optional.
Um unnötiges Rekompilieren nach Dokumentationsänderungen zu vermeiden, platzieren Sie die Abschnittsdokumentation in die C-Quellen, wo immer es möglich ist.

Dokumentieren von Symbolen
Jedes Symbol (function, macro, struct, enum, signal und property) wird in einem separaten Block dokumentiert. Der Block wird am besten nahe der Definition der Symbole platziert, so dass es leichter ist, diese synchron zu halten. Die Funktion wird üblicherweise in den C-Quellen definiert, »macro«, »struct« und »enum« dagegen in der Header-Datei.

Allgemeine Markierungen
Sie können Versionsinformationen zu allen Dokumentationselementen hinzufügen, um darauf hinzuweisen, wann eine API eingeführt oder wann sie als veraltet markiert wurde.

Versionierungs-Markierungen
Since: 	 Beschreibung, seit welcher Version des Codes die API verfügbar ist.
Deprecated: 	 Absatz, der darüber informiert, dass diese Funktion nicht mehr genutzt werden sollte. Die Beschreibung sollte einen Verweis auf die neue API enthalten.
Sie können Stabilitätsinformationen zu allen Dokumentationselementen hinzufügen, um darauf hinzuweisen, ob API-Stabilität für alle Minor-Veröffentlichungen des Projekts garantiert wird.
Die Standard-Stabilitätsstufe für alle Dokumentationselemente setzen Sie durch Übergabe des Arguments --default-stability an gtkdoc-mkdb in einem der nachfolgend beschriebenen Werte.

Stabilitäts-Markierungen
Stability: Stable 	 Markiert das Element als stabil. Dies bezieht sich auf öffentliche APIs, für die für alle zukünftigen Minor-Veröffentlichungen des Projekts Stabilität gewährleistet ist.
Stability: Unstable 	 Markiert das Element als instabil. Dies bezieht sich auf öffentliche APIs, die als Vorschau vor der endgültigen Stabilisierung gedacht sind.
Stability: Private 	 Markiert das Element als privat. Dies bezieht sich auf Schnittstellen, die von eng damit verknüpften Modulen genutzt werden kann, aber nicht von beliebigen Drittanbietern.

Allgemeine Markierungen

/**
 * foo_get_bar:
 * @foo: some foo
 *
 * Retrieves @foo's bar.
 *
 * Returns: @foo's bar
 *
 * Since: 2.6
 * Deprecated: 2.12: Use foo_baz_get_bar() instead.
 */
Bar *
foo_get_bar(Foo *foo)
{
...

Anmerkungen
Dokumentationsblöcke können Anmerkungs-Markierungen enthalten. Diese Markierungen werden als Tooltips (Minihilfen) dargestellt, die die jeweilige Bedeutung anzeigen. Sie werden von gobject-introspection genutzt, um Sprachbindungen zu erzeugen. Eine detaillierte Liste der unterstützten Markierungen finden Sie im Wiki.

Anmerkungen

/**
 * foo_get_bar: (annotation)
 * @foo: (annotation): some foo
 *
 * Retrieves @foo's bar.
 *
 * Returns: (annotation): @foo's bar
 */
...
/**
 * foo_set_bar_using_the_frobnicator: (annotation) (another annotation)
 *                                    (and another annotation)
 * @foo: (annotation) (another annotation): some foo
 *
 * Sets bar on @foo.
 */

Kommentarblock einer Funktion
Bitte denken Sie an:
Dokumentieren, ob zurückgegebene Objekte, Listen, Zeichenketten usw. befreit/dereferenziert/freigegeben werden.
Dokumentiert, ob Parameter NULL sein können, und was in diesem Fall geschieht.
Erwähnen Sie interessante Vorbedingungen (und nachfolgende Bedingungen), wo es nützlich erscheint.
GTK-Doc nimmt an, dass alle Symbole (Makros, Funktionen), die mit »_« beginnen, privat sind. Sie werden wie statische Funktionen behandelt.

Kommentarblock einer Funktion

/**
 * function_name:
 * @par1:  description of parameter 1. These can extend over more than
 * one line.
 * @par2:  description of parameter 2
 * @...: a %NULL-terminated list of bars
 *
 * The function description goes here. You can use @par1 to refer to parameters
 * so that they are highlighted in the output. You can also use %constant
 * for constants, function_name2() for functions and #GtkWidget for links to
 * other declarations (which may be documented elsewhere).
 *
 * Returns: an integer.
 *
 * Since: 2.2
 * Deprecated: 2.18: Use other_function() instead.
 */

Funktions-Markierungen
Returns: 	 Abschnitt, der das zurückgegebene Ergebnis beschreibt.
@...: 	 Wenn die Funktion variadische Argumente enthält, sollten Sie diese Markierung verwenden (@Varargs: funktioniert aus historischen Gründen ebenfalls).

Property-Kommentarblock

Property-Kommentarblock

/**
 * SomeWidget:some-property:
 *
 * Here you can document a property.
 */
g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);

Signal-Kommentarblock
Bitte denken Sie an:
Dokumentiert, wann ein Signal ausgegeben wird und ob es vor oder nach anderen Signalen ausgegeben wird.
Dokumentiert, was eine Anwendung in dem Signal-Handler tun könnte.

Signal-Kommentarblock

/**
 * FooWidget::foobarized:
 * @widget: the widget that received the signal
 * @foo: some foo
 * @bar: some bar
 *
 * The ::foobarized signal is emitted each time someone tries to foobarize @widget.
 */
foo_signals[FOOBARIZED] =
  g_signal_new ("foobarized",
                ...

Struct-Kommentarblock

Struct-Kommentarblock

/**
 * FooWidget:
 * @bar: some #gboolean
 *
 * This is the best widget, ever.
 */
typedef struct _FooWidget {
  GtkWidget parent_instance;

  gboolean bar;
} FooWidget;

Verwenden Sie /*< private >*/ vor den privaten »struct«-Feldern, die Sie verbergen wollen. Um das umgekehrte Verhalten zu erzielen, verwenden Sie /*< public >*/.
Wenn das erste Feld »g_iface«, »parent_instance« oder »parent_class« ist, wird es automatisch als privat angesehen und muss nicht im Kommentarblock erwähnt werden.
Struct-Kommentarblöcke können auch für GObjects und GObjectClasses verwendet werden. Es ist ratsam, einen Kommentarblock für eine Klasse hinzuzufügen, wenn diese vmethods enthält (dies ist die Art der Dokumentation dafür). Für GObject selbst können Sie die jeweiligen Abschnittsdokumentationen verwenden, wobei ein separater Block für das Instanz-Struct sinnvoll ist, sofern die Instanz öffentliche Felder enthält. Ein Nachteil ist hier, dass dadurch zwei gleichnamige Indexeinträge erstellt werden (die Struktur und der Abschnitt).

Enum-Kommentarblock

Enum-Kommentarblock

/**
 * Something:
 * @SOMETHING_FOO: something foo
 * @SOMETHING_BAR: something bar
 *
 * Enum values used for the thing, to specify the thing.
 */
typedef enum {
  SOMETHING_FOO,
  SOMETHING_BAR,
  /*< private >*/
  SOMETHING_COUNT
} Something;

Verwenden Sie /*< private >*/ vor den privaten »enum«-Werten, die Sie verbergen wollen. Um das umgekehrte Verhalten zu erzielen, verwenden Sie /*< public >*/.

Eingebettete Programmdokumentation
Dokumentieren Sie ein Programm und dessen Befehlszeilen-Schnittstelle mit eingebetteter Dokumentation.

Schlagwörter
PROGRAM 	 Definiert den Start einer Programmdokumentation
@short_description: 	 Definiert eine Kurzbeschreibung des Programms (optional).
@synopsis: 	 Definiert die Argumente oder eine Liste von Argumenten, die das Programm akzeptiert (optional).
@see_also: 	 Der Abschnitt »SEE ALSO« in den man-Pages (Unix-Handbuchseiten, optional).
@arg: 	 Argument(e), die dem Programm übergeben wurden, und die zugehörige Beschreibung (optional).
Description: 	 Eine ausführlichere Beschreibung des Programms.
Returns: 	 Geben Sie an, welche Wert(e) das Programm zurück gibt (optional).

Beispiel einer Programmdokumentation.

Programm-Dokumentationsblock

/**
 * PROGRAM:test-program
 * @short_description: A test program
 * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
 * @see_also: test(1)
 * @--arg1 *arg*: set arg1 to *arg*
 * @--arg2 *arg*: set arg2 to *arg*
 * @-v, --version: Print the version number
 * @-h, --help: Print the help message
 *
 * Long description of program.
 *
 * Returns: Zero on success, non-zero on failure
 */
int main(int argc, char *argv[])
{
	return 0;
}

Nützliche DocBook-Markierungen
Nachfolgend finden Sie einige DocBook-Markierungen, die beim Dokumentieren von Code nützlich sein können.
So erstellen Sie eine Verknüpfung zu einem anderen Abschnitt in den GTK-Docs:

<link linkend="glib-Hash-Tables">Hash Tables</link>

»linkend« ist dabei die SGML-XML-Kennung des obersten Elements der Seite, auf welche die Verknüpfung zielt (»gtk«, »gdk«, »glib«), danach folgt der Seitentitel ("Hash Tables"). Für Widgets ist dies einfach der Klassenname. Leerzeichen und Unterstriche werden SGML/XML-konform in »-« umgewandelt.
Für einen Bezug zu einer externen Funktion, z.B. einer C-Standardfunktion:

<function>...</function>

So fügen Sie Beispielcode ein: Vielleicht auch so, für sehr kurze Codeschnipsel, die keinen Titel benötigen:

<informalexample>
  <programlisting>
  ...
  </programlisting>
</informalexample>

Außerdem unterstützt GTK-Doc auch eine Abkürzung: |[ ... ]|
Für eine Liste mit Aufzählungszeichen:

<itemizedlist>
  <listitem>
    <para>
      ...
    </para>
  </listitem>
  <listitem>
    <para>
      ...
    </para>
  </listitem>
</itemizedlist>

Für eine nicht zum eigentlichen Text gehörende Notiz:

<note>
  <para>
    Make sure you free the data after use.
  </para>
</note>

Für einen Bezug zu einem Typ:

<type>unsigned char</type>

Für einen Bezug zu einer externen Struktur (die nicht in den GTK-Docs beschrieben wird):

<structname>XFontStruct</structname>

Für einen Bezug zu einem Feld einer Struktur:

<structfield>len</structfield>

Um sich auf einen Klassennamen zu beziehen kann man möglicherweise folgendes verwenden:

<classname>GtkWidget</classname>

Aber Sie verwenden vermutlich stattdessen #GtkWidget (um automatisch eine Verknüpfung zur GtkWidget-Seite zu erstellen - lesen Sie die Abkürzungen).
Zum Hervorheben von Text:

<emphasis>This is important</emphasis>

Für Dateinamen:

<filename>/home/user/documents</filename>

Für einen Bezug zu einem Schlüssel:

<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>