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.

Příklad 3-2Komentář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.

Příklad 3-3Komentář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.