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.
- 3.3.1. Obecné značky
- 3.3.2. Anotace
- 3.3.3. Komentářový blok pro funkci
- 3.3.4. Komentářový blok pro vlastnost
- 3.3.5. Komentářový blok pro signál
- 3.3.6. Komentářový blok pro strukturu
- 3.3.7. Komentářový blok pro výčty
3.3.1. 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é.
- 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.
- 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.
/** * 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) { ...
3.3.2. 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.
/** * 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. */
3.3.3. 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.
/** * 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(). */
- 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:).
3.3.4. Komentářový blok pro vlastnost
/** * SomeWidget:some-property: * * Zde vlastnost zdokumentujte. */ g_object_class_install_property (object_class, PROP_SOME_PROPERTY, …);
3.3.5. 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.
/** * 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[FOOBARIZE] = g_signal_new ("foobarize", ...
3.3.6. 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).
3.3.7. 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 >*/.