Wie funktioniert GTK-Doc?
GTK-Doc verwendet Funktionsdokumentationen, die sich in den Quelldateien innerhalb speziell formatierter Kommentarblöcke befinden, oder Dokumentation, die zu den von GTK-Doc verwendeten Vorlagendateien hinzugefügt wurde. Beachten Sie jedoch, dass GTK-Doc nur Funktionen dokumentieren wird, die in den Header-Dateien deklariert sind. Es erstellt keine Ausgaben für statische Funktionen.
GTK-Doc besteht aus einer Anzahl von Perl-Skripten, wovon jedes einen bestimmten Schritt in dem Prozess ausführt.
Dieser Vorgang umfasst fünf Hauptschritte:
-
Schreiben der Dokumentation. Der Autor ergänzt die Quelldateien um die Dokumentation für jede Funktion, jedes Makro usw. In der Vergangenheit wurden diese Informationen in erstellte Vorlagendateien eingegeben. Dies wird nicht mehr empfohlen.
-
Informationen über den Code sammeln. gtkdoc-scan analysiert die Header-Dateien des Code und sucht nach Funktionsdeklarationen, Macros, enum (Aufzählung), struct (Strukturen) und »unions«. Es erstellt die Datei <module>-decl-list.txt, welche eine Liste der Deklarationen enthält, und platziert diese in Abschnitte entsprechend der Header-Dateien, in der sie sind. Bei erster Ausführung wird diese Datei nach <module>-sections.txt kopiert. Der Autor kann die Abschnitte und die Reihenfolge der Deklarationen in gewünschter Reihenfolge neu anordnen. Die zweite erstellte Datei ist <module>-decl.txt. Diese Datei enthält alle Deklarationen, die vom Scanner gefunden wurden. Wenn aus irgendeinem Grund einige Symbole in der Dokumentation erscheinen sollen, wenn die volle Deklaration nicht vom Scanner gefunden werden kann oder die Deklaration anders erscheinen soll, kann man Entitäten ähnlich derer in<module>-decl.txt innerhalb <module>-overrides.txt platzieren.
gtkdoc-scangobj kann ebenso dazu verwendet werden, dynamisch eine Bibliothek über irgendeine GObject-Subklasse anzufragen, die sie exportiert. Es speichert Informationen über jede Objektposition in der Klassenhierarchie und über alle GObjekt-Eigenschaften und -Signale, die es bietet.
gtkdoc-scanobj sollte nicht weiter verwendet werden. Es war in der Vergangenheit notwendig, als GObject noch ein GtkObject innerhalb von gtk+ war.
-
Erstellen des SGML/XML und HTML/PDF. gtkdoc-mkdb wandelt die Vorlagen-Dateien in XML-Dateien in den Unterordner xml/ um. Wenn der Quellcode Dokumentation über Funktionen mittels speziellen Kommentarblöcken enthält, so wird diese hier eingepflegt. Wenn keine tmpl-Dateien eingesetzt werden, so wird nur Dokumentation von den Quell- und introspection-Daten gelesen.
gtkdoc-mkhtml konvertiert die XML-Dateien in HTML-Dateien im Unterordner html/. Ebenso konvertiert gtkdoc-mkpdf die XML-Dateien in ein PDF-Dokument namens <package>.pdf.
Dateien in xml/ und html/-Ordnern werden immer überschrieben. Niemand sollte diese direkt bearbeiten.
-
Querverweise zwischen Dokumenten korrigieren. Nach Intallation der HTML-Dateien kann gtkdoc-fixxref ausgeführt werden, um alle Querverweise zwischen separaten Dokumenten zu korrigieren. Die GTK+-Dokumentation zum Beispiel enthält viele Querverweise zu Typen, die im GLib-Handbuch dokumentiert sind. Beim Erstellen des Quellen-tarball zur Verteilung wandelt gtkdoc-rebase alle externen Verweise in Web-Verweise um. Beim Installieren verteilter (zuvor erstellter) Dokumente wird dieselbe Anwendung versuchen, Verweise zurück in lokale Verweise umzuwandeln (wo diese Dokumente installiert werden).