Dokumentování v kódu
GTK-Doc používá pro kód dokumentace komentáře se speciální syntaxí ve zdrojovém kódu. K tomu se ještě získávají informace o struktuře vašeho projektu z dalších zdrojů. V následujícím oddílu najdete všechny informace o syntaxi komentářů.

Umístění dokumentace
Dříve musela být většina dokumentace doplněná do souborů umístěných ve složce tmpl. Následkem toho bylo, že informace byly často neaktualizované a soubory měli tendenci způsobovat konflikty v systémech pro správu verzí.
Aby se předešlo těmto zmiňovaným problémům, předpokládáme vkládání dokumentace přímo do zdrojových kódů. Tato příručka bude popisovat pouze tento způsob dokumentování kódu.
Skener zvládá dobře většinu hlavičkových souborů C. V případě, že od něj obdržíte varování, které vypadá jako speciální případ, můžete GTK-Doc poradit, aby jej přeskakovala.

Komentářový blok GTK-Doc

#ifndef __GTK_DOC_IGNORE__
/* kód zde se nezpracovává */
#endif

Omezení
Uvědomte si, že GTK-Doc podporuje #ifndef(__GTK_DOC_IGNORE__), ale ne #if !defined(__GTK_DOC_IGNORE__) nebo jiné kombinace.

Dokumentační komentáře
Každý víceřádkový komentář, který je označený další „*“ navíc, je dokumentačním blokem a bude zpracovaný nástroji GTK-Doc.

Komentářový blok GTK-Doc

/**
 * identifikátor:
 * dokumentace …
 */

„identifikátor“ je jeden řádek s názvem položky, ke které se komentář vztahuje. Syntaxe se částečně liší podle položky. (DOPLNIT: přidat tabulku se seznamem identifikátorů)
Blok „dokumentace“ se rovněž liší pro různé typy symbolů. Symboly, které přebírají parametry, jako jsou funkce nebo makra, mají nejdříve popsané parametry, za kterými následuje prázdný řádek (pouze „*“). Za ním pak následuje podrobný popis. Všechny řádky (mimo seznamu programů a oddílu CDATA), které obsahují „ *“ (mezera hvězdička) se převedou na zalomení odstavce. Pokud zalomení odstavce nechcete, změňte to na „ * “ (mezera hvězdička mezera mezera). To se hodí na text s pevným formátem (výpis kódu).
Když píšete dokumentaci ke kódu, popište dva aspekty:
Co to je: Název třídy nebo funkce může být občas matoucí pro lidi, kteří používají něco jiného.
K čemu to je: Uveďte běžném použití. Dejte ho do souvislosti se zbytkem API.
Jednou z výhod hypertextu, oproti prostému textu, je možnost mít v dokumentu odkazy. Zápis správných značek pro odkazy může být úmorná práce. GTK-Doc se vám snaží pomoci několika užitečnými zkratkami.
Použijte funkce() pro odkaz na funkci nebo makro, které mají argumenty.
Použijte @parametr pro odkaz na parametry. Použijte to rovněž, když se odkazujete na parametry jiných funkcí, vztahujících se k popisované funkci.
Použijte %konstanta pro odkaz na konstantu, např. %G_TRAVERSE_LEAFS.
Použijte #symbol pro odkaz na jiný typ symbolu, např. strukturu, výčet a makro, který nemá argumenty.
Použijte #Objekt::signál pro odkaz na signál objektu GObject.
Použijte #Objekt:vlastnost pro odkaz na vlastnost objektu GObject.
Použijte #Struktura.pole pro odkaz na pole uvnitř struktury a #GObjectTřída.neco() pro odkaz na virtuální metodu.
V případě, že potřebujete ve své dokumentaci použít speciální znaky „<“, „>“, „()“, „@“, „%“ nebo „#“, aniž by je GTK-Doc změnilo, můžete místo nich použít použít entity XML „&lt;“, „&gt;“, „&lpar;“, „&rpar;“, „&commat;“, „&percnt;“ a „&num;“ nebo únikovou sekvenci se zpětným lomítkem „\“.
DocBook toho ale umí více, než jen odkazy. Může mít také seznamy, příklady, nadpisy a obrázky. Od verze 1.20 je dána přednost použití jen podmnožiny ze základní syntaxe formátování textu. Tato podmnožina se nazývá Markdown. Dokumentace ze starší verze GTK-Doc, která obsahuje Markdown, bude vygenerována tak, jak je. Například položky seznamu se objeví s pomlčkou na začátku.
I když je markdown v současnosti preferovaný, můžete míchat oba dohromady. Má to jediné omezení v tom, že můžete použít docbook xml v markdown, ale markdown v docbook xml podporován není.
Když ve starších vydáních GTK-Doc potřebujete podporu pro dodatečné formátování, musíte zapnout použití značek XML pro DocBook uvnitř dokumentačních komentářů pomocí --xml-mode (nebo --sgml-mode) v proměnné MKDB_OPTIONS v souboru Makefile.am.

Komentářový blok GTK-Doc používající značkovací jazyk

/**
 * identifikátor:
 *
 * odstavec dokumentace…
 *
 * # Podnadpis #
 *
 * ## Podnadpis druhé úrovně
 *
 * # Podnadpis s kotvou pro odkazy # {#heading-two}
 *
 * další dokumentace:
 *
 * - položka seznamu 1
 *
 *   Odstavec v rámci položky seznamu.
 *
 * - položka seznamu 2
 *
 * 1. číslovaná položka seznamu
 *
 * 2. další číslovaná položka seznamu
 *
 * Další odstavec. [Odkazy na webové stránky GNOME](http://www.gnome.org/)
 *
 * ![vložený obrázek](plot-result.png)
 *
 * [Odkaz na nadpis pomocí kotvy uvedené výše][heading-two]
 *
 * Příklad v jazyce C:
 * |[<!-- language="C" -->
 * GtkWidget *label = gtk_label_new ("Paráda!");
 * ]|
 */

Více příkladů k podporovaným značkám Markdown můžete najít v Referenční příručce k syntaxi Markdown pro dokumentaci GTK+.
Jak již bylo zmíněno dříve, slouží GTK-Doc pro dokumentování veřejného API. Tím pádem nemůžete psát dokumentaci pro statické symboly. Nicméně je vhodné komentovat i tyto symboly. Pomůže to ostatním porozumět vašemu kódu. Proto doporučujeme komentovat je pomocí normálních komentářů (bez druhé „*“ na prvním řádku). Pokud je budete v budoucnu chtít předělat na veřejné, jediné co budete muset udělat, je přidat do komentářového bloku jednu „*“ a na správné místo v souboru oddílů vložit název symbolu.

Dokumentování oddílů
Každý oddíl dokumentace obsahuje informaci o jedné třídě nebo modulu. Můžete do oddílu napsat blok, ve kterém je představíte. Stručný popis se rovněž použije v rámci tabulky s obsahem. Všechna @pole jsou volitelná.

Komentářový blok oddílu

/**
 * SECTION:meepapp
 * @short_description: třída plikace
 * @title: Aplikace Meep
 * @section_id:
 * @see_also: #MeepSettings
 * @stability: Stable
 * @include: meep/app.h
 * @image: application.png
 *
 * Třída aplikace starající se o…
 */

SECTION:<název> 	 Název prováže oddíl dokumentace s příslušnou částí v souboru <package>-sections.txt. Zde zadaný název musí odpovídat značce <SOUBOR> v souboru <package>-sections.txt.
@short_description 	 Jednořádkový popis oddílu, který se později objeví za odkazy v tabulce s obsahem a na začátku stránky oddílu.
@title 	 Název oddílu se standardně zvolí podle <name> v deklaraci SECTION. Lze jej ale určit i přímo v poli @title.
@section_id 	 Přepíše použití názvu jako identifikátoru oddílu. Pro objekty GObject se jako section_id použije <title> a pro ostatní oddíly to je <MODULE>-<title>.
@see_also 	 Seznam symbolů, které se vztahují k tomuto oddílu.
@stability 	 Informační popis úrovně stability tohoto API. Doporučujeme použít jeden z těchto termínů:
Stable (stabilní) – Záměrem stabilního rozhraní je umožnit libovolné třetí straně vyvinout aplikace využívající toto rozhraní, vydat je a moci se spolehnout, že poběží na všech podružných vydáních produktu (po té, co je rozhraní vydáno a v rámci stejné hlavní verze). I mezi hlavními vydáními se nekompatibilní změny očekávají zřídka v opravdu odůvodněných případech.
Unstable (nestabilní) – Nestabilní rozhraní je experimentální a přechodné. Typicky bývá dáno vývojářům k dispozici kvůli včasnému přístupu k novým a rychle se měnícím technologiím nebo kvůli poskytnutí provizorního řešení problému, kdy je předpokládané více obecné řešení. Není žádná záruka ohledně zdrojové či binární kompatibility při přechodu z jedné podružné verze na následujíc.
Private (soukromé) – Rozhraní, které může být použité v rámci zásobníku GNOME, ale není dokumentované pro koncového uživatele. Takové funkce by se měly používat jen určeným a dokumentovaným způsobem.
Internal (interní) – Rozhraní, které je určené pro interní potřeby modulu a nevyžaduje dokumentaci pro koncového uživatele. Funkce, které jsou nedokumentované, jsou považované za interní.
@include 	 Seznam souborů z #include oddělených čárkou, aby se zobrazily v oddílu anotace. Přepisuje globální hodnotu ze souboru oddílů nebo příkazové řádky. Tato položka je volitelná.
@image 	 Obrázek, který se má zobrazit na začátku referenční stránky k tomuto oddílu. Často se jedná o nějaký nákres, který schématicky znázorňuje podobu třídy nebo nákres se vztahy vůči jiným třídám. Tato položka je volitelná.
Aby se po změně dokumentace předešlo rekompilacím, které nejsou nutné, vložte, kde je to možné, dokumentaci oddílu do zdrojového kódu c.

Dokumentování symbolů
Každý symbol (funkce, makro, struktura, výčet, signál a vlastnost) se dokumentuje v odděleném bloku. Blok je nejlepší umístit v rámci definice symbolu, protože se tak snadno udržuje synchronizovaný. Z tohoto důvodu se funkce obvykle dokumentují ve zdrojovém kódu C a makra, struktury a výčty v hlavičkovém souboru.

Obecné značky
Informace o verzích můžete přidat ke všem prvkům dokumentace, abyste sdělili, kdy bylo API zavedeno, nebo kdy bylo označeno za zastaralé.

Značky pro verzování
Since: 	 Popisuje, od které verze kódu je API dostupné.
Deprecated: 	 Odstavec upozorňující, že by se tato funkce neměla nadále používat. Popis by měl čtenáře odkazovat na nové API.
Můžete také ke všem prvkům dokumentace přidat informaci o stabilitě, abyste dali najevo, že je u API zaručena stabilita pro všechna následující minoritní vydání projektu.
Výchozí stabilitu pro všechny prvky dokumentace můžete pomocí argumentu --default-stability s jednou u níže uvedených hodnot předat do gtkdoc-mkdb.

Značky pro stabilitu
Stability: Stable 	 Označuje prvek jako stabilní. Je to určeno pro veřejná API, která zaručují, že zůstanou stabilní po všechna minoritní vydání projektu.
Stability: Unstable 	 Označuje prvek jako nestabilní. Je to určeno pro veřejná API, která jsou vydána jako ukázky před tím, než jsou stabilizována.
Stability: Private 	 Označuje prvek jako soukromý. Je to určeno pro rozhraní, která mohou být použita přímo v modulu, ale ne kterýmikoliv třetími stranami.

Obecné značky

/**
 * foo_get_bar:
 * @foo: nějaké něco
 *
 * Získá @foo něčeho.
 *
 * Returns: @foo něčeho
 *
 * Since: 2.6
 * Deprecated: 2.12: Místo toho použijte foo_baz_get_bar().
 */
Bar *
foo_get_bar(Foo *foo)
{
...

Anotace
Dokumentační bloky mohou obsahovat anotační štítky. Tyto štítky budou zpracovány jako vysvětlivky popisující jejich význam. Používají se introspekcí objektu GObjekt k vygenerování vazby na další jazyky. Podrobný seznam podporovaných štítků můžete najít na wiki.

Anotace

/**
 * foo_get_bar: (annotation)
 * @foo: (annotation): nějaké něco
 *
 * Získá @foo něčeho.
 *
 * Returns: (annotation): @foo něčeho
 */
...
/**
 * foo_set_bar_using_the_frobnicator: (annotation) (annotation)
 *                                    (annotation) …
 * @foo: (annotation) (annotation) …: nějaké něco
 *
 * Nastaví něco na @foo.
 */

Komentářový blok pro funkci
Nezapomeňte prosím:
Zdokumentovat, jestli je třeba vracené objekty, seznamy, řetězce apod. uvolnit z paměti.
Zdokumentovat, jestli může parametr být NULL a co se stane, když tomu tak je.
Kde je to vhodné, zmínit úvodní a koncové podmínky.
Gtk-doc předpokládá, že všechny symboly (makra, funkce) začínající znakem „_“, jsou soukromé. Potom se s nimi zachází jako se statickými funkcemi.

Komentářový blok pro funkci

/**
 * function_name:
 * @par1:  popis parametru 1. Může zabírat více jak
 * jeden řádek.
 * @par2:  popis parametru 2
 * @...:  seznam proměnných parametrů zakončených NULL
 *
 * Zde pokračuje popis funkce. K odkazu na parametr můžete použit @par1,
 * takže bude ve výstupu zvýrazněný. Můžete také použít %constant pro
 * konstanty, function_name() pro funkce a #GtkWidget pro odkazy na jiné
 * deklarace (které mohou být zdokumentované jinde).
 *
 * Returns: celé číslo.
 *
 * Since: 2.2
 * Deprecated: 2.18: Místo toho použijte other_function().
 */

Značky pro funkce
Returns: 	 Odstavec popisující vracený výsledek.
@…: 	 Když má funkce proměnný počet argumentů, měli byste použít tuto značku (z historických důvodů funguje i @Varargs:).

Komentářový blok pro vlastnost

Komentářový blok pro vlastnost

/**
 * SomeWidget:some-property:
 *
 * Zde vlastnost zdokumentujte.
 */
g_object_class_install_property (object_class, PROP_SOME_PROPERTY, …);

Komentářový blok pro signál
Nezapomeňte prosím:
Zdokumentovat, kdy je signál vyslán a jestli je vyslána před nebo po ostatních signálech.
Zdokumentovat, co aplikace smí v obsluze signálu provádět.

Komentářový blok pro signál

/**
 * FooWidget::foobarized:
 * @widget: widget, který signál přijímá
 * @foo: nějaké něco
 * @bar: jiné něco
 *
 * Signál ::foobarized je vyslán pokaždé, když někdo zkusí něco s @widget.
 */
foo_signals[FOOBARIZED] =
  g_signal_new ("foobarized",
                ...

Komentářový blok pro strukturu

Komentářový blok pro strukturu

/**
 * FooWidget:
 * @bar: nějaká #gboolean
 *
 * Tohle je ten nejlepší widget.
 */
typedef struct _FooWidget {
  GtkWidget parent_instance;

  gboolean bar;
} FooWidget;

Před privátními poli struktury použijte /*< private >*/, abyste je skryli. K přesně opačnému účelu se používá /*< public >*/.
Pokud je prvním polem „g_iface“, „parent_instance“ nebo „parent_class“, bude za privátní považováno automaticky a není to zapotřebí zmiňovat v komentářovém bloku.
Komentářové bloky struktur můžete použít také pro objekty GObject a třídy GObjectClass. Obvykle je rozumné přidat komentářový blok pro třídu, pokud má virtuální metody (protože to je způsob, jakým je lze zdokumentovat). Pro vlastní GObject je možné použít příslušnou dokumentaci oddílu, který bude mít samostatný blok pro strukturu instance, což se může hodit, když má instance veřejná pole. Jedinou nevýhodou je, že se tím vytvoří dvě položky v rejstříku se stejným názvem (struktura a oddíl).

Komentářový blok pro výčty

Komentářový blok pro výčty

/**
 * Something:
 * @SOMETHING_FOO: nějaké něco
 * @SOMETHING_BAR: jiné něco
 *
 * Výčtové hodnoty používané pro určení věci.
 */
typedef enum {
  SOMETHING_FOO,
  SOMETHING_BAR,
  /*< private >*/
  SOMETHING_COUNT
} Something;

Před privátními výčtovými hodnotami použijte /*< private >*/, abyste je skryli. K přesně opačnému účelu se používá /*< public >*/.

Dokumentaci k vloženým programům
Programy a jejich rozhraní příkazového řádku můžete zdokumentovat pomocí vložené dokumentace.

Značky
PROGRAM 	 Definuje začátek dokumentace k programu.
@short_description: 	 Definuje krátký popis programu. (volitelné)
@synopsis: 	 Definuje argumenty nebo seznam argumentů, které program přebírá. (volitelné)
@see_also: 	 Část stránky oddílu „Viz také“. (volitelné)
@arg: 	 Argument(y) předávané do programu a jejich popis. (volitelné)
Description: 	 Úplný popis programu.
Returns: 	 Specifikuje, jakou hodnotu či více hodnot program vrací. (volitelné)

Příklad dokumentace k programu.

Komentářový blok pro program

/**
 * PROGRAM:test-program
 * @short_description: Testovací program
 * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
 * @see_also: test(1)
 * @--arg1 *arg*: nastaví arg1 do *arg*
 * @--arg2 *arg*: nastaví arg2 do *arg*
 * @-v, --version: Vypíše verzi programu
 * @-h, --help: Vypíše nápovědu k programu
 *
 * Úplný popis programu.
 *
 * Returns: Vrací nulu při úspěchu, nenulovou hodnotu při selhání.
 */
int main(int argc, char *argv[])
{
	return 0;
}

Užitečné značky DocBook
Zde jsou některé značky DocBook, které mají pro dokumentaci kódu největší význam.
Odkaz na jiný oddíl v dokumentaci GTK:

<link linkend="glib-Hash-Tables">Hašovací tabulky</link>

Odkazem je id SGML/XML v první položce stránky, na kterou chcete odkazovat. Pro většinu stránek je to v současnosti část („gtk“, „gdk“, „glib“) a potom název stránky („Hašovací tabulka“). Pro ovládací prvky je to název třídy. Mezery a podtržítka se převedou na „-“, aby to vyhovovalo SGML/XML.
Odkaz na externí funkci, například standardní funkci C:

<function>…</function>

Vložení ukázky kódu:

<example>
  <title>Používání GHashTable.</title>
  <programlisting>
      …
  </programlisting>
</example>

nebo pro velmi krátké úseky kódu, které nepotřebují nadpisy, je případně možné i:

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

V novějších verzích GTK-Doc je také podporované zkracování: |[ … ]|
Vložení seznamu s odrážkami:

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

Vložení poznámky, která se objeví mimo text:

<note>
  <para>
    Ujistěte se, že data po použití uvolníte.
  </para>
</note>

Odkaz na typ:

<type>unsigned char</type>

Odkaz na externí strukturu (která není popsaná v dokumentaci GTK):

<structname>XFontStruct</structname>

Odkaz na pole struktury:

<structfield>len</structfield>

Pro odkaz na název třídy by se dal nejspíše použít:

<classname>GtkWidget</classname>

ale pravděpodobně místo toho použijete #GtkWidget (aby se automaticky vytvořil odkaz na stránku ovládacího prvku, viz zkratky).
Zvýrazněný text:

<emphasis>Toto je důležité</emphasis>

Pro název souboru použijte:

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

Odkaz na použití klávesy:

<keycombo><keycap>Ctrl</keycap><keycap>L</keycap></keycombo>