Dokumentationskommentarer

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

Exempel 3-2GTK-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.

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