<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>
Pro dokumentaci API používejte gtk-doc s nastavením pro udržování aktuální podoby. (<link xref="#gtk-doc"/>)
</item>

      <item>
Používejte prvky XML pro zahrnutí externích symbolů do dokumentace. (<link xref="#build-system"/>)
</item>

      <item>
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"/>)
</item>

      <item>
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"/>)
</item>

      <item>
Do veškeré dokumentace k API přidejte anotace k introspekci. (<link xref="#introspection-annotations"/>)
</item>

      <item>
Do všech dokumentací k API doplňte řádky Since. (<link xref="#symbol-versioning"/>)
</item>

      <item>
Povolte testy gtk-doc. (<link xref="#keeping-up-to-date"/>)
</item>

    </list>

  </synopsis>

  <section id="gtk-doc">

    <title>gtk-doc</title>

    
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.

  </section>

  <section id="build-system">

    <title>Systém sestavení</title>

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

    
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 <file>docs/version.xml.in</file>, který bude obsahovat:

    @PACKAGE_VERSION@

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

  </section>

  <section id="standard-layout">

    <title>Standardní uspořádání</title>

    
Použití standardního uspořádání pro obsah, oddíly, dodatky atd. znamená, že stejnou šablonu <file>název-projektu-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.

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

    <listing>

      <title><file>název-projektu-docs.xml</file></title>

      <desc>Soubor gtk-doc s šablonou nejvyšší úrovně pro projekt</desc>

      <xi:include href="example-docs.xml" parse="text"/>

    </listing>

  </section>

  <section id="licensing">

    <title>Licencování</title>

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

  </section>

  <section id="public-api">

    <title>Veřejná API</title>

    
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 <file>modulename-sections.txt</file> vaší dokumentace.

    
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 get_type() pro vaši třídu musí být uvedená v <file>modulename.types</file>.

  </section>

  <section id="introspection-annotations">

    <title>Poznámky k introspekci</title>

    
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ů:

    <list type="numbered">

      <item>
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.
</item>

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

    </list>

    
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 <link xref="introspection">pokynech k introspekci</link>.

  </section>

  <section id="symbol-versioning">

    <title>Číslování verzí symbolů</title>

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

    
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 <file>*-docs.xml</file> 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>

  </section>

  <section id="dbus-api">

    <title>API pro D-Bus</title>

    
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.

    
Soubory DocBook mohou být vloženy do souboru <file>*-docs.xml</file> 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 <file>Makefile.am</file> pro gtk-doc, jinak sestavení selže. (Je to kvůli nápravě situací, kdy složka builddir není shodná se srcdir.)

  </section>

  <section id="keeping-up-to-date">

    <title>Udržování dokumentace v aktuálním stavu</title>

    
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.

    
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:

    TESTS = $(GTKDOC_CHECK)

    
Budou pak spouštěny jako součást <cmd>make check</cmd>.

  </section>

</page>