Úprava souboru oddílů

Soubor oddílů se používá k organizování výstupu dokumentace z GTK-Doc. Zde se určuje, který symbol náleží ke kterému modulu nebo třídě, a řídí se viditelnost (jestli je veřejný nebo soukromý).

Soubor oddílů je prostý textový soubor, ve kterém jsou oddíly oddělené značkami. Prázdné řádky se ignorují a s řádky začínajícími „#“ se zachází jako s komentářovými řádky.

Přestože díky značkám vypadá soubor podobně jako XML, není tomu tak. Neuzavírejte prosím značky jako je <SUBSECTION>.

Příklad 4-5Vkládání generovaných oddílů
<INCLUDE>libmeep/meep.h</INCLUDE>

<SECTION>
<FILE>meepapp</FILE>
<TITLE>MeepApp</TITLE>
MeepApp
<SUBSECTION Standard>
MEEP_APP
...
MeepAppClass
meep_app_get_type
</SECTION>

Značka <FILE> … </FILE> se používá k určení názvu souboru bez přípony. Například použití „<FILE>gnome-config</FILE>“ bude mít v deklaracích oddílu za následek výstup do souboru šablony tmpl/gnome-config.sgml, který bude převeden do souboru sgml/gnome-config.sgml ve formátu DocBook SGML nebo do souboru xml/gnome-config.xml ve formátu DocBook XML. (Název souboru HTML vychází z názvu modulu a názvu oddílu, případně pro GObject z názvu třídy GObject převedeného na malá písmena.)

Značka <TITLE> … </TITLE> se používá k určení názvu oddílu. To je použitelné pouze dříve, než je poprvé vytvořena šablona (pokud se používá), protože název nastavený v šabloně tento název přepíše. Navíc je považována za zastaralou v případě, že se používá komentář SECTION ve zdrojovém kódu.

Můžete také seskupovat položky v oddílu pomocí značky <SUBSECTION>. V současnosti způsobí prázdný řádek mezi pododdíly v souhrnné části. Můžete také použít <SUBSECTION Standard> pro standardní deklarace GObject (například funkce jako je g_object_get_type, makra jako G_OBJECT(), G_IS_OBJECT() atd.). V současnosti jsou tyto v dokumentaci vynechané. Můžete také použít <SUBSECTION Private> pro privátní deklarace, které ve výsledku nebudou (jedná se o ruční způsob, jak zabránit varovným hlášením o nepoužitých deklaracích). Pokud vaše knihovna obsahuje privátní typy, u kterých nechcete, aby se objevily v hierarchii objektů a v seznamu implementovaných nebo vyžadovaných rozhraní, přidejte je do pododdílu Private. Jestli umístit struktury jako GObject a GObjectClass do veřejné nebo standardní části záleží na tom, jestli mají veřejné položky (proměnné, virtuální metody).

Můžete také použít <INCLUDE> ... </INCLUDE> k určení #include souborů, které jsou zobrazené v souhrnné části. Obsahuje čárkami oddělený seznam jednotlivých #include souborů, bez lomených závorek. Když je nastavíte mimo kterýkoliv oddíl, budou fungovat pro všechny oddíly až do konce souboru. Když je nastavíte v konkrétním oddílu, použijí se jen pro něj.