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á.

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

The name links the section documentation to the respective part in the <package>-sections.txt file. The name given here should match the <FILE> tag in the <package>-sections.txt file.

@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.