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

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.

Příklad 3-5Obecné 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)
{
...

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.

Příklad 3-6Anotace
/**
 * 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.

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

3.3.4. Komentářový blok pro vlastnost

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

Příklad 3-9Komentář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[FOOBARIZE] =
  g_signal_new ("foobarize",
                ...

3.3.6. Komentářový blok pro strukturu

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

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