Hur fungerar GTK-Doc?

GTK-Doc fungerar så att det använder dokumentation för funktioner placerad inuti källkodsfilerna i speciellt formaterade kommentarsblock, eller dokumentation som lagts till i mallfilerna som GTK-Doc använder (notera dock att GTK-Doc endast kommer att dokumentera funktioner som deklarerats i huvudfiler; det kommer inte att producera utdata för statiska funktioner).

GTK-Doc består av ett antal perl-skript som vart och ett utför olika steg i processen.

Det finns 5 huvudsteg i processen:

  1. Skriva dokumentationen. Författaren fyller i källkodsfilerna med dokumentation för varje funktion, makro, union, etc. (Tidigare matades informationen in i genererade mallfiler, något som inte rekommenderas längre).

  2. Samla ihop information om koden. gtkdoc-scan söker genom huvudfilerna för koden och letar efter deklarationer av funktioner, makron, uppräkningar, strukturer och unioner. Det skapar sedan filen <module>-decl-list.txt som innehåller en lista över deklarationerna, och placerar dem i avsnitt efter vilken huvudfil de finns i. Vid första körningen kommer denna fil att kopieras till <module>-sections.txt. Författaren kan, genom att omarrangera avsnitten och ändra ordningen för deklarationerna inom dem, framställa den önskade, slutgiltiga ordningen. Den andra filen det genererar är <module>-decl.txt. Denna fil innehåller de fullständiga deklarationerna som hittats av detektorn. Om man av något skäl vill att vissa symboler ska visas i dokumentation då den fullständiga deklarationen inte kan hittas av detektorn, eller om deklarationen ska visas annorlunda, kan man placera rader liknande de som finns i <module>-decl.txt i <module>-overrides.txt.

    gtkdoc-scangobj kan också användas för att dynamiskt fråga ett bibliotek om vilka GObject-underklasser det exporterar. Det sparar information om varje objekts position i klasshierarkin och om vilka GObject-egenskaper och signaler det tillhandahåller.

    gtkdoc-scanobj bör inte användas längre. Det behövdes tidigare när GObject fortfarande var GtkObject inuti gtk+.

  3. Generera XML och HTML/PDF. gtkdoc-mkdb förvandlar mallfilerna till XML-filer i underkatalogen xml/. Om källkoden innehåller dokumentation över funktioner i speciella kommentarsblock, så kommer denna att sammanfogas här. Om det inte finns några tmpl-filer som används så kommer det endast att läsa dokumentation från källkoden och introspektionsdata.

    gtkdoc-mkhtml förvandlar XML-filer till HTML-filer i underkatalogen html/. På samma sätt förvandlar gtkdoc-mkpdf XML-filerna till ett PDF-dokument kallat <package>.pdf.

    Filer i xml/- och html/-katalogerna skrivs alltid över. Man bör aldrig redigera dem direkt.

  4. Fixa korsreferenser mellan dokument. Efter att ha installerat HTML-filerna kan gtkdoc-fixxref köras för att fixa korsreferenser mellan separata dokument. Till exempel GTK+-dokumentationen innehåller många korsreferenser till typer som dokumenterats i GLib-manualen. När tar-arkivet med källkod skapas för distribution, förvandlar gtkdoc-rebase alla externa länkar till webblänkar. När (förgenererad) distribuerad dokumentation installeras kommer samma program att försöka att förvandla länkarna tillbaka till lokala länkar (i de fall där dokumentationen finns installerad).