Federico Mena-Quintero
federico@gnome.org 2013
Philip Withnall
philip.withnall@collabora.co.uk 2015
Tým GTK+
Doplnění dokumentace ke knihovnám a k API

# Dokumentace

#

        Shrnutí

          Pro dokumentaci API používejte gtk-doc s nastavením pro udržování aktuální podoby. ()
          Používejte prvky XML pro zahrnutí externích symbolů do dokumentace. ()
          Používejte jednotný standardní obsah ve všech dokumentacích k API, aby šla udržovat podle běžných zvyklostí. ()
          Používejte gdbus-codegen k vygenerování dokumentace k API pro D-Bus, která se zahrne do sestavení gtk-doc. ()
          Do veškeré dokumentace k API přidejte anotace k introspekci. ()
          Do všech dokumentací k API doplňte řádky Since. ()
          Povolte testy gtk-doc. ()

# gtk-doc

Upřednostňovaným systémem pro dokumentovaní knihoven GNOME je gtk-doc, který získává vložené komentáře z kódu, aby z nich sestavil dokument DocBook a sadu stránek HTML. Ty je pak možné číst v aplikaci Devhelp. Velká část infrastruktury GNOME je postavena tak, aby pracoval s dokumentací napsanou pomocí gtk-doc.

# Systém sestavení

Při začleňování gtk-doc do systému sestavení u projektu se řiďte instrukcemi v příručce k gtk-doc. Přípomínáme, že soubor sections.txt je sice vygenerován automaticky, ale jen při prvním spuštění gtk-doc. Následně již generován není a musí být udržován ručně. Proto by měl být také v systému pro správu verzí.

Měli byste používat variantu gtk-doc `no-tmpl` a režim XML namísto SGML. (Režim tmpl a SGML jsou zastaralé a pomalejší než XML.)

Když je zapotřebí vložit číslo balíčku do textu dokumentace, vytvořte soubor s názvem docs/version.xml.in, který bude obsahovat:

@PACKAGE_VERSION@

Přidejte jej do `AC_CONFIG_FILES` v configure.ac a pak jej vložte do hlavního souboru dokumentace (*-docs.xml) pomocí: `<!ENTITY version SYSTEM "version.xml">` v `DOCTYPE` na začátku dokumentu. Verzi balíčku pak můžete vkládat pomocí `&version;`.

# Standardní uspořádání

Použití standardního uspořádání pro obsah, oddíly, dodatky atd. znamená, že stejnou šablonu název-projektu-docs.xml můžete znovu použít s minimálními změnami pro různé projekty. A rovněž to znamená, že uspořádání dokumentace bude obdobné napříč všemi projekty, takže se v ní vývojáři budou lépe orientovat.

Je doporučováno následující uspořádání:

## název-projektu-docs.xml

Soubor gtk-doc s šablonou nejvyšší úrovně pro projekt

# Licencování

Je důležité, aby licence použitá pro referenční příručku k API, byla čistá, hlavně když je součástí dokumentace i ukázkový kód, který je možné kopírovat.

Typicky používá projekt pro svoji referenční příručku tu stejnou licenci, jako pro vlastní kód projektu, aby se předešlo nejasnostem. Některé projekty zase používají pro veškerou svoji dokumentaci CC-BY-SA 3.0. Volba je čistě na vás.

Jak je ukázáno ve Standardním uspořádání, měli byste do souboru gtk-doc DocBook nejvyšší úrovně vložit licence.xml, který poskytne úplný text licence vaší dokumentace.

# Veřejná API

Veškerá veřejná API musí mít komentáře gtk-doc. Pro funkce by měly být umístěny ve zdrojovém souboru, přímo nad funkcí.

/** * gtk_get_flow: * @widget: a #GtkWidget * * Gets the flow of a widget. * * Note that flows may be laminar or turbulent... * * Returns: (transfer none): the flow of @widget */ GtkFlow * gtk_get_flow (GtkWidget *widget) {

...

}

Dokumentační komentáře pro makra, typy funkcí, struktury tříd atd. by měly být umístěny vedle definici, typicky v hlavičkových souborech.

Úvody k jednotlivým oddílům by měly být umístěné ve zdrojových souborech, které popisují, za hlavičkou s licencí:

/** * SECTION:gtksizerequest * @Short_Description: Height-for-width geometry management * @Title: GtkSizeRequest * * The GtkSizeRequest interface is GTK+'s height-for-width (and * width-for-height) geometry management system. * ... */

Mějte na paměti, že aby se funkce, makro, typ funkce nebo typ struktura byly součástí, je zapotřebí je uvést v souboru modulename-sections.txt vaší dokumentace.

Správné zdokumentování nové třídy vyžaduje poskytnutí jejího vlastního oddílu v modulename-sections.txt, musí být vložená v vašem modulename-docs.sgml nejvyšší úrovně a funkce `get_type()` pro vaši třídu musí být uvedená v modulename.types.

# Poznámky k introspekci

Každý komentář gtk-doc by měl mít příslušné anotace k introspekci GObject. To je užitečné ze dvou důvodů:

Přidá to důležitou informaci o typech parametrů, možných prázdných hodnotách a správě paměti do dokumentace k API C vygenerované pomocí gtk-doc.

Umožní to veřejným API navázat se automaticky na další jazyky, jako třeba Python nebo JavaScript.

Anotace k introspekci přidává do API (funkce, parametry funkcí, návratové hodnoty funkcí, struktury, vlastnosti GObject, signály GObject) informace, které ve strojově čitelné podobě API v C nejsou jinak dostupné a existují jen ve formě čitelné člověkem v dokumentaci nebo jako zvyklosti. Proto jsou velmi důležité.

V komentářích gtk-doc by se měla dávat přednost anotacím před variantou čitelnou pro člověka. Například, když dokumentujete parametr funkce, který může nabývat hodnoty `NULL`, použijte namísto nějakého textu raději anotaci `(nullable)`:

/** * my_function: * @parameter: (nullable): some parameter which affects something * * Body of the function documentation. */

Použijte namísto:

/** * my_bad_function: * @parameter: some parameter which affects something, or %NULL to ignore * * Bad body of the function documentation. */

Více informací k introspekci najdete v pokynech k introspekci.

# Číslování verzí symbolů

Kdykoliv je do veřejného API přidán nějaký symbol, měl by pro něj být přidán i dokumentační komentář. Ten by měl vždy obsahovat řádek `Since` s číslem verze vydání balíčku, který poprvé obsahuje nové API. Mělo by se jednat o číslo verze, které se právě nachází v configure.ac, za předpokladu, že používáte zvyšování čísla verze po vydání.

Například:

/** * my_function: * @param: some parameter * * Body of the function documentation. * * Since: 0.5.0 */

gtk-doc používá tyto informace k vygenerování rejstříku API přidaných v jednotlivých vydáních. Do *-docs.xml by jako dodatek mělo být přidáno následující:

<part> <title>Appendices</title> <index id="api-index-full"> <title>API Index</title> <xi:include href="xml/api-index-full.xml"><xi:fallback/></xi:include> </index> <index id="api-index-deprecated"> <title>Index of deprecated symbols</title> <xi:include href="xml/api-index-deprecated.xml"><xi:fallback/></xi:include> </index> <index role="0.1.0"> <title>Index of new symbols in 0.1.0</title> <xi:include href="xml/api-index-0.1.0.xml"><xi:fallback/></xi:include> </index> <!-- More versions here. --> <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include> </part>

# API pro D-Bus

Popisy rozhraní D-Bus obsahují dokumentační komentáře a ty je možné získat z XML pomocí gdbus-codegen a nasměrovat do souborů DocBook, aby byly začleněny pomocí gtk-doc.

Soubory DocBook mohou být vloženy do souboru *-docs.xml pomocí:

<chapter> <title>C Interfaces</title> <partintro> <para>C wrappers for the D-Bus interfaces.</para> </partintro>

<xi:include href="xml/SomeDBusService.xml"/> <xi:include href="xml/SomeOtherService.xml"/> </chapter>

Vygenerované soubory XML musí být zahrnuté v proměnné `content_files` ve vašem Makefile.am pro gtk-doc, jinak sestavení selže. (Je to kvůli nápravě situací, kdy složka `builddir` není shodná se `srcdir`.)

# Udržování dokumentace v aktuálním stavu

gtk-doc obsahuje podporu pro kontrolu dokumentace pomocí pár základních testů. Mimo jiných věcí se zkontroluje, jestli jsou všechny verze indexů vložené v hlavním souboru *-docs.xml a jestli jsou zdokumentované všechny symboly.

Tyto testy by měly být vždy povolené přidáním následujícího do Makefile.am pro váš gtk-doc:

TESTS = $(GTKDOC_CHECK)

Budou pak spouštěny jako součást make check.