Att dokumentera koden
GTK-Doc använder källkodskommentarer med en speciell syntax för koddokumentation. Vidare så hämtar det information om din projektstruktur från olika källor. Under nästa avsnitt kommer du att hitta information om syntaxen i kommentarerna.

Dokumentationsplacering
Tidigare var det tvunget att fylla i största delen av dokumentationen i filer som fanns i katalogen tmpl. Detta hade nackdelen att informationen ofta inte uppdaterades och att filen också ofta orsakade konflikter med versionshanteringssystem.
För att undvika de nämnda problemen föreslår vi att placera dokumentationen i källkoden. Denna manual kommer endast att beskriva detta sättet att dokumentera kod.
Detektorn kan hantera majoriteten av C-huvuden bra. I det fall när du får varningar från detektorn som ser ut som ett specialfall, kan du tipsa GTK-Doc att hoppa över dem.

GTK-Doc-kommentarsblock

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

Begränsningar
Notera att GTK-Doc har stöd för #ifndef(__GTK_DOC_IGNORE__) men inte #if !defined(__GTK_DOC_IGNORE__) eller andra kombinationer.

Dokumentationskommentarer
En flerradskommentar som börjar med en extra ”*” markerar ett dokumentationsblock som kommer att hanteras av GTK-Doc-verktygen.

GTK-Doc-kommentarsblock

/**
 * identifierare:
 * dokumentation …
 */

'Identifierare' är en rad med namnet på det objekt som kommentaren är relaterad till. Syntaxen skiljer sig lite beroende på objekt. (TODO lägg till tabell som visar identifierare)
Blocket 'dokumentation' skiljer sig också för varje symboltyp. Symboltyper som får parametrar så som funktioner eller makron har en parameterbeskrivning först, åtföljd av en blankrad (bara en ”*”). Efteråt följer den detaljerade beskrivningen. Alla rader (utanför programlistningar och CDATA-avsnitt) som endast innehåller ” *” (blanksteg-asterisk) konverteras till styckeavgränsare. Om du inte vill ha en styckeavgränsare, ändra till ” * ” (blanksteg-asterisk-blanksteg-blanksteg). Detta är användbart i förformaterad text (kodlistningar).
När du dokumenterar kod, beskriv två aspekter:
Vad är detta: Namnet på en klass eller en funktion kan ibland vara vilseledande för personer med annan bakgrund.
Vad gör det: Berättar om vanliga användningsfall. Sätter det i relation med det andra API:t.
En fördel med hypertext framför vanlig text är möjligheten att ha länkar i dokumentet. Att skriva korrekta taggar för en länk kan dock vara tröttsamt. GTK-Doc hjälper då till med att tillhandahålla flera användbara förkortningar.
Använd funktion() för att referera till funktioner eller makron som tar argument.
Använd @param för att referera till parametrar. Använd också detta när du refererar till parametrar för andra funktioner, relaterade till den som beskrivs.
Använd %konstant för att referera till en konstant, t.ex. %G_TRAVERSE_LEAFS.
Använd #symbol för att referera till andra typer av symboler, t.ex. strukturer eller uppräkningar och makron som inte tar argument.
Använd #Objekt::signal för att referera till en GObject-signal.
Använd #Objekt:egenskap för att referera till en GObject-egenskap.
Använd #Struktur.fält för att referera till ett fält inuti en struktur och #GObjectKlass.foo_bar() för att referera till en virtuell metod.
Om du behöver använda specialtecken ”<”, ”>”, ”()”, ”@”, ”%” eller ”#” i din dokumentation utan att GTK-Doc ändrar dem kan du använda XML-entiteterna ”&lt;”, ”&gt;”, ”&lpar;”, ”&rpar;”, ”&commat;”, ”&percnt;” respektive ”&num;” eller använda kontrollsekvensen ”\”.
DocBook kan mer än bara länkar. Du kan också ha listor, exempel, rubriker och bilder. Från och med version 1.20, är det föredragna sättet att använda en delmängd av den grundläggande textformateringssyntaxen som kallas Markdown. Äldre GTK-Doc-versioner kommer dokumentation som inkluderar markdown att renderas som den är. Till exempel kommer listobjekt att visas som att de börjar med ett bindestreck.
Då markdown numera föredras kan du blanda båda. En begränsning här är att du kan använda docbook-xml inuti markdown, men markdown inuti docbook-xml stöds inte.
I äldre GTK-Doc-versioner var du tvungen, om du ville ha stöd för ytterligare formatering, att aktivera användningen av docbook-XML-taggar inuti dok-kommentarer genom att lägga till --xml-mode (eller --sgml-mode) i variabeln MKDB_OPTIONS inuti Makefile.am.

GTK-Doc-kommentarsblock som använder Markdown

/**
 * Identifierare:
 *
 * stycke med dokumentation …
 *
 * # Underrubrik #
 *
 * ## Underunderrubrik
 *
 * # Underrubrik med länkankare # {#andra-rubriken}
 *
 * mer dokumentation:
 *
 * - listobjekt 1
 *
 *   Stycke inuti listobjekt.
 *
 * - listobjekt 2
 *
 * 1. numrerat listobjekt
 *
 * 2. ytterligare ett numrerat listobjekt
 *
 * Ett annat stycke. [En länk till GNOME:s webbplats](http://www.gnome.org/)
 *
 * ![en bild](resultatgraf.png)
 *
 * [En länk till rubrikankaret ovan][andra-rubriken]
 *
 * Ett C-exempel:
 * |[<!-- language="C" -->
 * GtkWidget *label = gtk_label_new ("Vackert!");
 * ]|
 */

Fler exempel på vilka markdown-taggar som stöds hittas i Referensen för GTK+-dokumentationens markdown-syntax.
Som redan nämnts är GTK-Doc avsett för att dokumentera publika API:er. Du kan därför inte skriva dokumentation för statiska symboler. Likväl är det bra att kommentera dessa symboler. Det hjälper andra att förstå din kod. Därför rekommenderar vi att du kommenterar dessa med normala kommenterar (utan den andra ”*” på den första raden). Om funktionen vid ett senare tillfälle måste göras publik är allt du behöver göra att lägga till ytterligare en ”*” i kommentarsblocket och infoga symbolnamnet på rätt ställe i avsnittsfilen.

Dokumentationsavsnitt
Varje avsnitt av dokumentation innehåller information om en klass eller en modul. För att introducera komponenten kan man skriva ett avsnittsblock. Den korta beskrivningen används också i innehållsförteckningen. Alla @fälten är valfria.

Kommentarsblock för avsnitt

/**
 * SECTION:meepapp
 * @short_description: programklassen
 * @title: Meep-programmet
 * @section_id:
 * @see_also: #MeepSettings
 * @stability: Stable
 * @include: meep/app.h
 * @image: application.png
 *
 * Programklassen hanterar …
 */

SECTION:<namn> 	 Namnet länkar till avsnittsdokumentationen för respektive del i filen <paket>-sections.txt. Namnet som anges här bör matcha taggen <FILE> i filen <paket>-sections.txt.
@short_description 	 En enradsbeskrivning av avsnittet som senare kommer att visas efter länkar i innehållsförteckningen och lägst upp på avsnittssidan.
@title 	 Avsnittstiteln är som standard <namn> från SECTION-deklarationen. Den kan åsidosättas med fältet @title.
@section_id 	 Åsidosätter användningen av titeln som avsnittsidentifierare. För GObjects används <title> som ett section_id och för andra avsnitt är det <MODULE>-<title>.
@see_also 	 En lista över symboler som är relaterade till detta avsnitt.
@stability 	 En informell beskrivning över stabiliteten för detta API. Vi rekommenderar att använda en av dessa termer:
Stable - Avsikten med ett stabilt gränssnitt är att möjliggöra för tredje parter att utveckla program mot dessa gränssnitt, släppa dem och vara säkra på att de kommer att köra på alla programfixversioner av produkten (efter den i vilken gränssnittet introducerats, och inom samma huvudversion). Även vid en ny huvudversion förväntas inkompatibla ändringar vara få och vara väl motiverade.
Unstable - Instabila gränssnitt är experimentella eller i en övergångsfas. De används typiskt för att ge utomstående utvecklare tidig tillgång till ny eller snabbt föränderlig teknologi, eller för att tillhandahålla provisoriska lösningar för ett problem där en mer generell lösning förutses. Inga påståenden görs om endera källkods- eller binärkompatibilitet från en programfixversion till nästa.
Private - Ett gränssnitt som kan användas inom GNOME-stacken i sig, men som inte dokumenterats för slutanvändare. Sådana funktioner bör endast användas på angivna och dokumenterade sätt.
Internal - ett gränssnitt som är internt för en modul och inte behöver slutanvändardokumentation. Funktioner som är odokumenterade förutsätts vara interna.
@include 	 #include-filerna som ska visas i avsnittssammanfattningen (en kommaavgränsad lista), vilket åsidosätter det globala värdet från avsnittsfilen eller kommandoraden. Detta objekt är valfritt.
@image 	 Bilden som ska visas längst upp på referenssidan för detta avsnitt. Detta kommer ofta att vara någon form av diagram för att illustrera det visuella utseendet för en klass eller ett diagram över dess relationer med andra klasser. Detta objekt är valfritt.
För att undvika onödig omkompilering efter dokumentationsändringar, placera avsnittsdokumentationen i c-källkoden där möjligt.

Dokumentationssymboler
Varje symbol (funktion, makro, struktur, uppräkning, signal och egenskap) är dokumenterad i ett separat block. Blocket placeras bäst intill definitionen av symbolerna så att det är enkelt att hålla dem synkroniserade. Därför dokumenteras funktioner vanligtvis i c-källkoden och makron, strukturer och uppräkningar i huvudfilen.

Generella taggar
Du kan lägga till versioneringsinformation i alla dokumentationselement för att berätta när ett API introducerats eller blev föråldrat.

Versioneringstaggar
Since: 	 Beskrivning över från och med vilken version av koden som API:t är tillgängligt.
Deprecated: 	 Stycke som betecknar att denna funktion inte bör användas längre. Beskrivningen bör peka läsaren vidare till det nya API:t.
Du kan också lägga till stabilitetsinformation för alla dokumentationselement för att indikera huruvida API-stabilitet är garanterad för dem för alla framtida programfix-versioner av projektet.
Standardvärdet för stabilitetsnivån för alla dokumentations element kan ställas in genom att ange argumentet --default-stability till gtkdoc-mkdb med endera av värdena nedan.

Stabilitetstaggar
Stability: Stable 	 Markera elementet som stabilt. Detta är för publika API:er som är garanterade att hållas stabila i alla framtida programfix-versioner av projektet.
Stability: Unstable 	 Markera elementet som instabilt. Detta är för publika API:er som är släppta på förhand innan de blivit stabiliserade.
Stability: Private 	 Markera element som privat. Detta är avsett för gränssnitt som kan användas av tätt sammankopplade moduler, men inte av godtyckliga tredje parter.

Generella taggar

/**
 * foo_get_bar:
 * @foo: någon foo
 *
 * Hämtar bar från @foo.
 *
 * Returns: bar från @foo
 *
 * Since: 2.6
 * Deprecated: 2.12: Använd foo_baz_get_bar() istället.
 */
Bar *
foo_get_bar(Foo *foo)
{
…

Noteringar
Dokumentationsblock kan innehålla noteringstaggar. Dessa taggar kommer att renderas som verktygstips som beskriver deras syfte. Taggarna används av gobject-introspection för att generera språkbindningar. En detaljerad lista över vilka taggar som stöds hittas på wikisidan.

Noteringar

/**
 * foo_get_bar: (notering)
 * @foo: (notering): någon foo
 *
 * Hämtar bar från @foo.
 *
 * Returns: (notering): bar från @foo
 */
...
/**
 * foo_set_bar_using_the_frobnicator: (notering) (an annan notering)
 *                                    (ytterligare en annan notering)
 * @foo: (notering) (en annan notering): någon foo
 *
 * Ställer in bar i @foo.
 */

Kommentarsblock för funktioner
Kom ihåg att:
Dokumentera huruvida returnerade objekt, listor, strängar, etc. bör frigöras/avrefereras/släppas.
Dokumentera huruvida parametrar tillåts vara NULL och vad som händer om de är NULL.
Nämn intressanta förvillkor och eftervillkor där lämpligt.
Gtk-doc förutsätter att alla symboler (makron, funktioner) som börjar med ”_” är privata. De behandlas på samma sätt som statiska funktioner.

Kommentarsblock för funktioner

/**
 * funktionsnamn:
 * @par1:  beskrivning av parameter 1. Dessa kan sträcka sig
 *  över mer än en rad.
 * @par2:  beskrivning av parameter 2
 * @...: en %NULL-terminerad lista av flera bar
 *
 * Funktionsbeskrivningen ska vara här. Du kan använda @par1 för att
 * referera till parametrar så att de färgmarkeras i utdata. Du kan också
 * använda %konstant för konstanter, funktionsnamn2() för funktioner och
 * #GtkWidget för länkar till andra deklarationer (vilka kan vara dokumenterade
 * på annat håll).
 *
 * Returns: ett heltal.
 *
 * Since: 2.2
 * Deprecated: 2.18: Använd annan_funktion() istället.
 */

Funktions-taggar
Returns: 	 Stycke som beskriver det returnerade resultatet.
@...: 	 Om funktionen har variadiska argument bör du använda denna tagg (@Varargs: fungerar också på grund av historiska skäl).

Kommentarsblock för egenskaper

Kommentarsblock för egenskaper

/**
 * EnKomponent:en-egenskap:
 *
 * Här kan du dokumentera en egenskap.
 */
g_object_class_install_property (object_class, PROP_EN_EGENSKAP, …);

Kommentarsblock för signaler
Kom ihåg att:
Dokumentera när en signal sänds ut och huruvida den sänds ut före eller efter andra signaler.
Dokumentera vad ett program kan göra i signalhanteraren.

Kommentarsblock för signaler

/**
 * FooWidget::foobariserad:
 * @widget: komponenten som erhåller signalen
 * @foo: någon foo
 * @bar: någon bar
 *
 * Signalen ::foobariserad sänds ut varje gång någon försöker att foobarisera @widget.
 */
foo_signals[FOOBARIZE] =
  g_signal_new ("foobariserad",
                ...

Kommentarsblock för strukturer

Kommentarsblock för strukturer

/**
 * FooWidget:
 * @bar: någon #gboolean
 *
 * Detta är den bästa komponenten någonsin.
 */
typedef struct _FooWidget {
  GtkWidget parent_instance;

  gboolean bar;
} FooWidget;

Använd/*< private >*/ före privata strukturfält som du vill gömma. Använd /*< public >*/ för det omvända beteendet.
Om det första fältet är ”g_iface”, ”parent_instance” eller ”parent_class” kommer det att anses vara privat automatiskt och behöver inte nämnas i kommentarsblocket.
Kommentarsblock för strukturer kan också användas för GObject och GObjectClass. Det är vanligtvis en bra idé att lägga till ett kommentarsblock för en klass om den har virtuella metoder (då detta är sättet på vilket de kan dokumenteras). För GObject i sig kan man använda den relaterade avsnittsdokumentationen, och ha ett separat block för varje instansstruktur vore användbart om instansen har publika fält. En nackdel här är att det skapar två indexposter med samma namn (strukturen och avsnittet).

Kommentarsblock för uppräkningar

Kommentarsblock för uppräkningar

/**
 * Something:
 * @SOMETHING_FOO: någonting foo
 * @SOMETHING_BAR: någonting bar
 *
 * Uppräkningsvärden som används för saken, för att specificera saken.
 */
typedef enum {
  SOMETHING_FOO,
  SOMETHING_BAR,
  /*< private >*/
  SOMETHING_COUNT
} Something;

Använd /*< private >*/ före privata uppräkningsvärden som du vill gömma. Använd /*< public >*/ för det omvända beteendet.

Infogad programdokumentation
Du kan dokumentera program och deras kommandoradsgränssnitt med infogad dokumentation.

Taggar
PROGRAM 	 Definierar början av programdokumentationen.
@short_description: 	 Definierar en kort beskrivning av programmet. (Valfritt)
@synopsis: 	 Definierar argumenten, eller en lista av argument som programmet kan ta. (Valfritt)
@see_also: 	 Se vidare i manualavsnitt. (Valfritt)
@arg: 	 Argument som skickas vidare till programmet och deras beskrivningar. (Valfritt)
Beskrivning: 	 En längre beskrivning av programmet.
Returns: 	 Ange vilka värden programmet returnerar. (Valfritt)

Exempel på programdokumentation.

Dokumentationsblock för program

/**
 * PROGRAM:test-program
 * @short_description: Ett testprogram
 * @synopsis: test-program [*FLAGGOR*...] --arg1 *arg* *FIL*
 * @see_also: test(1)
 * @--arg1 *arg*: ställ in arg1 på *arg*
 * @--arg2 *arg*: ställ in arg2 på *arg*
 * @-v, --version: Skriv ut versionsinformation
 * @-h, --help: Skriv ut hjälpmeddelandet
 *
 * En längre beskrivning av programmet.
 *
 * Returns: Noll vid framgång, icke-noll vid fel
 */
int main(int argc, char *argv[])
{
	return 0;
}

Användbara DocBook-taggar
Här är några DocBook-taggar som är användbara när man dokumenterar koden.
För att länka till ett annat avsnitt i GTK-dokumentationen:

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

Länkslutet är XGML/XML-id:t för toppnivåobjektet på sidan du vill länka till. För de flesta sidorna är detta för närvarande delen (”gtk”, ”gdk”, ”glib”) och sedan sidans titel (”Hashtabeller”). För komponenter är detta helt enkelt klassnamnet. Blanksteg och understreck konverteras till ”-” för att överensstämma med SGML/XML.
För att referera till en extern funktion, t.ex. en standardfunktion i C:

<function>…</function>

För att inkludera exempelkod:

<example>
  <title>Att använda en hashtabell.</title>
  <programlisting>
      …
  </programlisting>
</example>

eller möjligen följande, för väldigt korta kodfragment som inte behöver en titel:

<informalexample>
  <programlisting>
  …
  </programlisting>
</informalexample>

För det senare fallet har GTK-Doc också stöd för förkortningen: |[ … ]|
För att inkludera punktlistor:

<itemizedlist>
  <listitem>
    <para>
      …
    </para>
  </listitem>
  <listitem>
    <para>
      …
    </para>
  </listitem>
</itemizedlist>

För att inkludera en not som skiljer sig från texten:

<note>
  <para>
    Säkerställ att du frigjort data efter användning.
  </para>
</note>

För att refera till en typ:

<type>unsigned char</type>

För att referera till en extern struktur (som inte beskrivs i GTK-dokumentationen):

<structname>XFontStruct</structname>

För att referera till ett fält för en struktur:

<structfield>len</structfield>

För att referera till ett klassnamn kan vi möjligen använda:

<classname>GtkWidget</classname>

men du kommer troligt att använda #GtkWidget istället (för att automatiskt skapa en länk till GtkWidget-sidan - se förkortningarna).
För att betona text:

<emphasis>Detta är viktigt</emphasis>

För filnamn använd:

<filename>/home/användare/dokument</filename>

För att referera till tangenter använd:

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