<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" xmlns:xi="http://www.w3.org/2003/XInclude" type="topic" id="documentation" xml:lang="cs">
<info>
<link type="guide" xref="index#general-guidelines"/>
<credit type="author copyright">
<name>Federico Mena-Quintero</name>
<email its:translate="no">federico@gnome.org</email>
<years>2013</years>
</credit>
<credit type="author copyright">
<name>Philip Withnall</name>
<email its:translate="no">philip.withnall@collabora.co.uk</email>
<years>2015</years>
</credit>
<credit type="author copyright">
<name>Tým GTK+</name>
</credit>
<include xmlns="http://www.w3.org/2001/XInclude" href="cc-by-sa-3-0.xml"/>
<desc>Doplnění dokumentace ke knihovnám a k API</desc>
</info>
<title>Dokumentace</title>
<synopsis>
<title>Shrnutí</title>
<list>
<item><p>Pro dokumentaci API používejte gtk-doc s nastavením pro udržování aktuální podoby. (<link xref="#gtk-doc"/>)</p></item>
<item><p>Používejte prvky XML pro zahrnutí externích symbolů do dokumentace. (<link xref="#build-system"/>)</p></item>
<item><p>Používejte jednotný standardní obsah ve všech dokumentacích k API, aby šla udržovat podle běžných zvyklostí. (<link xref="#standard-layout"/>)</p></item>
<item><p>Používejte <cmd>gdbus-codegen</cmd> k vygenerování dokumentace k API pro D-Bus, která se zahrne do sestavení gtk-doc. (<link xref="#dbus-api"/>)</p></item>
<item><p>Do veškeré dokumentace k API přidejte anotace k introspekci. (<link xref="#introspection-annotations"/>)</p></item>
<item><p>Do všech dokumentací k API doplňte řádky <code>Since</code>. (<link xref="#symbol-versioning"/>)</p></item>
<item><p>Povolte testy gtk-doc. (<link xref="#keeping-up-to-date"/>)</p></item>
</list>
</synopsis>
<section id="gtk-doc">
<title>gtk-doc</title>
<p>Upřednostňovaným systémem pro dokumentovaní knihoven GNOME je <link href="http://www.gtk.org/gtk-doc/">gtk-doc</link>, který získává vložené komentáře z kódu, aby z nich sestavil dokument <link href="http://docbook.org/">DocBook</link> a sadu stránek HTML. Ty je pak možné číst v aplikaci <link href="https://wiki.gnome.org/Apps/Devhelp">Devhelp</link>. Velká část infrastruktury GNOME je postavena tak, aby pracoval s dokumentací napsanou pomocí gtk-doc.</p>
</section>
<section id="build-system">
<title>Systém sestavení</title>
<p>Při začleňování gtk-doc do systému sestavení u projektu <link href="https://developer.gnome.org/gtk-doc-manual/stable/settingup.html.en">se řiďte instrukcemi v příručce k gtk-doc</link>. Přípomínáme, že soubor <file>sections.txt</file> 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é <link href="https://developer.gnome.org/gtk-doc-manual/stable/settingup_vcs.html.en">v systému pro správu verzí</link>.</p>
<p>Měli byste používat variantu gtk-doc <code>no-tmpl</code> a režim XML namísto SGML. (Režim tmpl a SGML jsou zastaralé a pomalejší než XML.)</p>
<p>Když je zapotřebí vložit číslo balíčku do textu dokumentace, vytvořte soubor s názvem <file>docs/version.xml.in</file>, který bude obsahovat:</p>
<code>@PACKAGE_VERSION@</code>
<p>Přidejte jej do <code>AC_CONFIG_FILES</code> v <file>configure.ac</file> a pak jej vložte do hlavního souboru dokumentace (<file>*-docs.xml</file>) pomocí: <code><!ENTITY version SYSTEM "version.xml"></code> v <code>DOCTYPE</code> na začátku dokumentu. Verzi balíčku pak můžete vkládat pomocí <code>&version;</code>.</p>
</section>
<section id="standard-layout">
<title>Standardní uspořádání</title>
<p>Použití standardního uspořádání pro obsah, oddíly, dodatky atd. znamená, že stejnou šablonu <file><var>název-projektu</var>-docs.xml</file> 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.</p>
<p>Je doporučováno následující uspořádání:</p>
<listing>
<title><file><var>název-projektu</var>-docs.xml</file></title>
<desc>Soubor gtk-doc s šablonou nejvyšší úrovně pro projekt</desc>
<code mime="application/docbook+xml"><xi:include href="example-docs.xml" parse="text"/></code>
</listing>
</section>
<section id="licensing">
<title>Licencování</title>
<p>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.</p>
<p>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.</p>
<p>Jak je ukázáno ve <link xref="#standard-layout">Standardním uspořádání</link>, měli byste do souboru gtk-doc DocBook nejvyšší úrovně vložit <file>licence.xml</file>, který poskytne úplný text licence vaší dokumentace.</p>
</section>
<section id="public-api">
<title>Veřejná API</title>
<p>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í.</p>
<code mime="text/x-csrc" style="valid">/**
* 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)
{
...
}</code>
<p>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.</p>
<p>Ú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í:</p>
<code mime="text/x-csrc" style="valid">/**
* 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.
* ...
*/</code>
<p>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 <file>modulename-sections.txt</file> vaší dokumentace.</p>
<p>Správné zdokumentování nové třídy vyžaduje poskytnutí jejího vlastního oddílu v <file>modulename-sections.txt</file>, musí být vložená v vašem <file>modulename-docs.sgml</file> nejvyšší úrovně a funkce <code>get_type()</code> pro vaši třídu musí být uvedená v <file>modulename.types</file>.</p>
</section>
<section id="introspection-annotations">
<title>Poznámky k introspekci</title>
<p>Každý komentář gtk-doc by měl mít příslušné <link href="https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations">anotace k introspekci GObject</link>. To je užitečné ze dvou důvodů:</p>
<list type="numbered">
<item><p>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.</p></item>
<item><p>Umožní to veřejným API navázat se automaticky na další jazyky, jako třeba Python nebo JavaScript.</p></item>
</list>
<p>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é.</p>
<p>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 <code>NULL</code>, použijte namísto nějakého textu raději anotaci <code>(nullable)</code>:</p>
<code mime="text/x-csrc" style="valid">/**
* my_function:
* @parameter: (nullable): some parameter which affects something
*
* Body of the function documentation.
*/</code>
<p>Použijte namísto:</p>
<code mime="text/x-csrc" style="invalid">/**
* my_bad_function:
* @parameter: some parameter which affects something, or %NULL to ignore
*
* Bad body of the function documentation.
*/</code>
<p>Více informací k introspekci najdete v <link xref="introspection">pokynech k introspekci</link>.</p>
</section>
<section id="symbol-versioning">
<title>Číslování verzí symbolů</title>
<p>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 <code>Since</code> 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 <file>configure.ac</file>, za předpokladu, že používáte <link xref="versioning#release-process">zvyšování čísla verze po vydání</link>.</p>
<p>Například:</p>
<code mime="text/x-csrc" style="valid">/**
* my_function:
* @param: some parameter
*
* Body of the function documentation.
*
* Since: 0.5.0
*/</code>
<p>gtk-doc používá tyto informace k vygenerování rejstříku API přidaných v jednotlivých vydáních. Do <file>*-docs.xml</file> by jako dodatek mělo být přidáno následující:</p>
<code mime="application/docbook+xml"><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></code>
</section>
<section id="dbus-api">
<title>API pro D-Bus</title>
<p>Popisy rozhraní D-Bus obsahují dokumentační komentáře a ty je možné získat z XML pomocí <cmd>gdbus-codegen</cmd> a nasměrovat do souborů DocBook, aby byly začleněny pomocí gtk-doc.</p>
<p>Soubory DocBook mohou být vloženy do souboru <file>*-docs.xml</file> pomocí:</p>
<code mime="application/docbook+xml"><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></code>
<p>Vygenerované soubory XML musí být zahrnuté v proměnné <code>content_files</code> ve vašem <file>Makefile.am</file> pro gtk-doc, jinak sestavení selže. (Je to kvůli nápravě situací, kdy složka <code>builddir</code> není shodná se <code>srcdir</code>.)</p>
</section>
<section id="keeping-up-to-date">
<title>Udržování dokumentace v aktuálním stavu</title>
<p>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 <file>*-docs.xml</file> a jestli jsou zdokumentované všechny symboly.</p>
<p>Tyto testy by měly být vždy povolené přidáním následujícího do <file>Makefile.am</file> pro váš gtk-doc:</p>
<code>TESTS = $(GTKDOC_CHECK)</code>
<p>Budou pak spouštěny jako součást <cmd>make check</cmd>.</p>
</section>
</page>