included"> ]> Příručka ke GTK-Doc 1.24.1 Uživatelská příručka pro vývojáře s instrukcemi k používání GTK-Doc. Chris Lyttle
chris@wilddev.net
 Dan Mueth
d-mueth@uchicago.edu
 Stefan Sauer (Kost)
ensonic@users.sf.net
 Projekt GTK-Doc
gtk-doc-list@gnome.org
 2000, 2005 Dan Mueth and Chris Lyttle 2007-2019 Stefan Sauer (Kost) Je povoleno kopírovat, šířit a/nebo upravovat tento dokument za podmínek GNU Free Documentation License ve verzi 1.1 nebo v jakékoli další verzi vydané nadací Free Software Foundation, s neměnnými oddíly, bez textů předních desek a bez textů zadních desek. Kopie licence je součástí. Mnoho názvů použitých firmami k zviditelnění produktů nebo služeb jsou ochranné známky. Na místech, kde jsou tyto názvy v dokumentaci použity a členové Dokumentačního projektu GNOME jsou si vědomi skutečnosti, že se jedná o ochrannou známku, je takovýto název psán velkými písmeny celý nebo s velkým písmenem na začátku. 1.33.0 1. října 2020 mc verze gtk4 1.32.1 15. srpna 2019 ss vývojová verze 1.32 15. srpna 2019 ss opravné vydání 1.31 5. srpna 2019 ss přepracování a větší pokrytí testy 1.30 8. května 2019 ss větší pokrytí testy 1.29 28. srpna 2018 ss opravy chyb 1.28 24. března 2018 ss opravy chyb 1.27 7. prosince 2017 ss detailní vyladění portu v jazyce Python 1.26 11. srpen 2017 ss přenesení všech nástrojů z jazyků Perl/Bash do jazyka Python 1.25 21. březen 2016 ss opravy chyb, pročištění testů 1.24 29. května 2015 ss oprava chyby 1.23 17. květen 2015 ss oprava chyby 1.22 07. květen 2015 ss opravy chyb, odstranění zastaralých věcí 1.21 17. červenec 2014 ss opravy chyb, odstranění zastaralých věcí 1.20 16. únor 2014 ss opravy chyb, podpora značkovacího jazyka, vylepšení stylů 1.19 05. červen 2013 ss opravy chyb 1.18 14. září 2011 ss opravy chyb, zrychlení, podpora značkovacího jazyka 1.17 26. únor 2011 sk aktualizace kvůli neodkladné opravě chyby 1.16 14. leden 2011 sk opravy chyb, vylepšení vzhledu 1.15 21. květen 2010 sk opravy chyb a regresí 1.14 28. březen 2010 sk opravy chyb a vylepšení výkonu 1.13 18. prosinec 2009 sk aktualizace poškozeného balíčku 1.12 18. prosinec 2009 sk nové funkce nástroje a opravy chyb 1.11 16. listopad 2008 mal přechod na doc-utils z GNOME Úvod Tato kapitola je úvodem do GTK-Doc a podává přehled o tom, co to je a jak to použít. Co je to GTK-Doc? GTK-Doc is used to document C code. It is typically used to document the public API of libraries, such as GLib-based libraries, but it can also be used to document application code. Jak GTK-Doc pracuje? GTK-Doc works by reading specially-formatted comment blocks placed inside the source files to document symbols such as functions, macros, structs, enums, etc. (though note that for most kind of symbols GTK-Doc will only document the symbols that are declared in header files; for example it won't produce output for static functions). GTK-Doc also reads template files where documentation can be added there as well. GTK-Doc consists of a number of programs, each performing a different step in the process. The main steps are: Psaní dokumentace. Autor doplní soubory se zdrojovým kódem s dokumentací pro každou funkci, makro, strukturu, výčet atd. Shromáždění informací o kódu. gtkdoc-scan projde hlavičkové soubory kódu a vyhledá při tom deklarace funkcí, maker, výčtů, struktur a sjednocení. Tím se vytvoří soubor <module>-decl-list.txt obsahující seznam deklarací, které jsou rozdělené do oddílů podle hlavičkového souboru, ze kterého pochází. Při prvním spuštění se tento soubor zkopíruje do <module>-sections.txt. Autor může změnit uspořádání oddílů a jejich pořadí v rámci deklarací tak, jak to požaduje ve výsledku. Druhý soubor, který se vytvoří, je <module>-decl.txt. Tento soubor obsahuje úplné deklarace nalezené při procházení. Pokud byste z nějakého důvodu chtěli v dokumentaci zahrnout symbol, který při procházení nebyl nalezen, nebo jeho deklarace vypadá jinak, můžete jej umístit podobně jako v <module>-decl.txt do <module>-overrides.txt. Dá se také použít gtkdoc-scanobj k dynamickým dotazům do knihoven na podtřídy objektu GObject, které exportují. Tím se uloží informace o pozici každého objektu v hierarchii tříd a o argumentech a signálech objektu GObject, které poskytují. gtkdoc-scanobj should not be used anymore. It was needed in the past when GObject was still GtkObject inside GTK. Generating the XML and HTML/PDF. gtkdoc-mkdb turns the template files into XML files in the xml/ subdirectory. If the source code contains documentation for symbols, using the special comment blocks, it gets merged in here. If there are no tmpl files used it only reads docs from sources and introspection data. gtkdoc-mkhtml převádí soubory XML na soubory HTML v podsložce html/. Obdobně gtkdoc-mkpdf převádí soubory XML na dokument PDF nazvaný <balíček>.pdf. Soubory ve složkách xml/ a html/ jsou vždy přepsány. Nikdy by neměly být upravovány přímo. Fixing up cross-references between documents. After installing the HTML files, gtkdoc-fixxref can be run to fix up any cross-references between separate documents. For example, the GTK documentation contains many cross-references to types documented in the GLib manual. When creating the source tarball for distribution, gtkdoc-rebase turns all external links into web-links. When installing distributed (pregenerated) docs the same application will try to turn links back to local links (where those docs are installed). Jak získat GTK-Doc? Požadavky Python 2/3 – hlavní skripty jsou v jazyce Python. xsltproc – procesor xslt z knihovny libxslt xmlsoft.org/XSLT/ docbook-xsl – stylopisy XSL pro docbook sourceforge.net/projects/docbook/files/docbook-xsl Něco z source-highlight, highlight nebo vim – (volitelné) používá se pro zvýraznění syntaxe u příkladů O aplikaci GTK-Doc Historicky se GTK-Doc používalo ke generování šablonových souborů ze zdrojových kódů. Tyto šablonové soubory pak mohli vývojáři používat ke vkládání dokumentace k API. Tento postup byl dosti nepohodlný, protože vyžadovat udržování vygenerovaných souborů ve správě verzí. Proto od verze 1.9 přichází GTK-Doc s možností vkládat všechny informace o API do komentářů ve zdrojových kódech, čímž se podpora šablon stává nadbytečnou. Ve verzi 1.26 byla podpora šablon odstraněna. (DOPLNIT) (autoři, webové stránky, poštovní konference, licence, plány do budoucna, srovnání s ostatními podobnými systémy.) O této příručce (DOPLNIT) (k čemu je určená, kde ji můžete získat, licence) Nastavení projektu Tato kapitola popisuje kroky, které jsou nutné pro integraci GTK-Doc do vašeho projektu. Integrace GTK-Doc do projektu zahrnuje následující kroky: Přípravu struktury složek a vytvoření požadovaných konfiguračních souborů pro dokumentaci GTK-Doc (viz Nastavení kostry dokumentace). Přizpůsobení sestavovacího systému, aby sestavoval vaši dokumentaci pomocí nástrojů GTK-Doc. Je podporováno více sestavovacích systémů, v této příručce je popsáno, jak integrovat GTK-Doc s Autotools, CMake a prostými soubory Makefiles. Přidání souborů specifických pro GTK-Doc do správy verzí a rozhodnutí, které soubory se mají ignorovat (viz Integrace se systémem správy verzí). Následující oddíly předpokládají, že pracujeme na projektu nazvaném meep. Tento projekt obsahuje dva balíčky (nebo moduly), knihovnu nazvanou libmeep a uživatelskou aplikaci nazvanou meeper. Nastavení kostry dokumentace Zaběhnutým zvykem je umístit dokumentaci do složky nazvané docs ve složce nejvyšší úrovně projektu. Obvykle rozlišujeme mezi referenční dokumentací zaměřenou na vývojáře a uživatelskou příručkou zaměřenou na koncového uživatele. Opět je zvykem mít zvláštní složku pro každou z obou zmíněných. Obvykle umisťujeme referenční dokumentaci do složky nazvané reference a uživatelskou příručku do složky nazvané help. V souladu se zmíněnými zvyky by dokumentace pro naši knihovnu libmeep byla umístěna do docs/reference/libmeep. U balíčků s jedinou knihovnou nebo referenční dokumentací by bylo možné ji umístit přímo do docs/reference. Není povinné použít uvedenou konvenci, ale pokud se rozhodnete použít jinou strukturu složek, musíte upravit konfiguraci sestavovacího systému, aby se s ní shodoval. V následujících oddílech budeme uvažovat strukturu složek pro náš projekt meep, který používá výše uvedené konvence. Příklad struktury složek projektu <emphasis>meep</emphasis> meep/ docs/ reference/ # referenční dokumentace libmeep/ meeper/ help/ # volitelné: uživatelská příručka meeper/ src/ libmeep/ meeper/ Integrace s Autotools Integrace GTK-Doc do sestavovacího systému založeného na Autotools vyžaduje následující kroky: Zajistit, že gtkdocize se spustí právě jednou před skriptem configure. Pokud je přítomen skript autogen.sh, upravte jej, aby kontroloval GTK-Doc a přidejte volání gtkdocize. Hlavním účelem gtkdocize je vytvořit Makefile gtk-doc.make a definici makra gtk-doc.m4 dostupnou sestavovacímu systému, buď zkopírováním do projektu nebo vytvořením odkazu. Přidat potřebná makra autoconf do configure.ac, abyste povolili GTK-Doc v sestavovacím systému a konfigurace GTK-Doc mohla jít přes generovaný skript configure. Mimo jiné pomocí registrace přepínače --enable-gtk-doc ve skriptu configure. Vytvořit skript automake pro jednotlivé aplikace a knihovny ve svém projektu. V příkladu použitém v této dokumentaci je tento krok použit jak pro meeper, tak pro libmeep. V následujícím oddíle provedeme výše zmíněné kroky v opačném pořadí. Začneme se skripty automake a budeme postupovat až k configure.ac a autogen.sh. Pak si ukážeme, jak povolit GTK-Doc v sestavovacím systému a jak sestavit dokumentaci. Integrace s automake Jako první nakopírujte Makefile.am z podsložky examples ve složce gtkdoc-sources do složky s referenční dokumentací svého projektu (např. ./docs/reference/<package>). Místní kopie by měla být k dispozici např. pod /usr/share/doc/gtk-doc-tools/examples/Makefile.am. Pokud máte více balíčků s dokumentací, opakujte tento krok pro každý z nich. Nezapomeňte přidat jednotlivé Makefile.am do makra AC_CONFIG_FILES v configure.ac. Pro docs/reference/libmeep/Makefile.am budete potřebovat přidat záznam docs/reference/libmeep/Makefile do AC_CONFIG_FILES. Příklad struktury složek s <filename>Makefiles.am</filename> meep/ docs/ reference/ # referenční dokumentace libmeep/ Makefile.am meeper/ Makefile.am help/ # volitelné: uživatelská příručka meeper/ src/ libmeep/ meeper/ Dále je třeba přizpůsobit zkopírované soubory Makefile a dodat hodnoty pro různé parametry v jednotlivých Makefile.am. Všechna nastavení mají komentáře s popisem svého účelu a jak nastavení přizpůsobit. Většina nastavení má doplňující příznaky předávané do dotyčných nástrojů, které je umí použít. Každý nástroj má proměnnou ve formátu (např. nástroj gtkdoc-mkhtml má volbu nazvanou MKHTML_OPTIONS). Všechny nástroje podporují pro vypsání podporovaných přepínačů. Následující seznam vysvětluje nejpodstatnější volby. Na další volby se podívejte do ukázkového Makefile.am. se používá k poskytnutí názvu balíčku, který je dokumentován (např. meeper nebo libmeep). se používá k určení umístění zdrojové složky, ve které GTK-Doc hledá dokumentaci API. Obvykle to je DOC_SOURCE_DIR=$(top_srcdir)/src nebo podsložka této složky. a se používají pro závislosti. Obě volby přebírají file-glob (např. HFILE_GLOB=$(top_srcdir)/src/*.c). Dokumentace se znovu sestaví, když se kterýkoliv z odpovídajících souborů změní. umožňuje určit dodatečné hlavičkové soubory, které se mají zahrnout při procházení pro dokumentaci k API, a které nejsou k nalezení pod složkou DOC_SOURCE_DIR (např. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h). umožňuje určit dodatečné hlavičkové soubory nebo složky, které se mají ignorovat při procházení pro dokumentaci k API. Použijte základní název ze souboru nebo složky (např. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder). umožňuje určit soubory s obrázky, které se zkopírují do složky s generovanou dokumentací. Pokud jsou součástí vaší dokumentace API nějaké obrázky, je třeba je přidat do této volby (např. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png). umožňuje určit dodatečné soubory, které se mají vložit pomocí $(DOC_MAIN_SGML_FILE) (např. content_files=running.xml building.xml changes-2.0.xml). umožňuje určit soubory, ve kterých jsou rozvinuty zkratky gtk-doc, jako je třeba #GtkWidget (např. expand_content_files=running.xml). Integrace s autoconf Integrace s autoconf je velmi jednoduchá a skládá se z jednoho povinného kroku a dalšího volitelného (ale doporučeného) kroku. Prvním krokem je přidat makro GTK_DOC_CHECK do skriptu configure.ac. Tím se zaregistruje několik konfiguračních voleb, které povolí GTK-Doc a umožní vám nastavit výchozí argumenty pro gtkdocize. Ujistěte se, že makro GTK_DOC_CHECK není odsazené od kraje. Makro musí začínat na začátku řádku a nesmí začínat bílými znaky. Druhým krokem je přidat do configure.ac makro AC_CONFIG_MACRO_DIR(m4). Není to sice nutné, ale pomůže to gtkdocize automaticky zkopírovat definici makra (např. gtk-doc.m4), která obsahuje makro GTK_DOC_CHECK, do složky s makry ve vašem projektu. Bez toho se může stát, že makro GTK_DOC_CHECK nemusí být nalezeno a budete muset nástroji aclocal výslovně uvést, kde soubor s definicí makra najít. Minimální integrace s autoconf # doporučeno: nastaví složku m4 AC_CONFIG_MACRO_DIR(m4) # volitelné: zaregistruje gtk-doc v configure GTK_DOC_CHECK([1.28]) Výše uvedený příklad funguje, ale vyžaduje, aby všichni vývojáři měli nainstalováno gtk-doc. Lepším způsobem je zařídit, aby sestavení dokumentace bylo volitelné, jak je ukázáno v následujícím příkladu: Integrace s volitelnými závislostttmi gtk-doc m4_ifdef([GTK_DOC_CHECK], [ # doporučeno: nastaví složku m4 AC_CONFIG_MACRO_DIR(m4) # volitelné: zaregistruje gtk-doc v configure GTK_DOC_CHECK([1.28]) ],[ AM_CONDITIONAL([ENABLE_GTK_DOC], false) ]) První argument se používá ke kontrole verze GTK-Doc v průběhu konfigurace. Druhý, volitelný argument používá nástroj gtkdocize. Makro GTK_DOC_CHECK také přidává několik přepínačů pro configure: --with-html-dir=CESTA: cesta, kam se má dokumentace nainstalovat --enable-gtk-doc: použít k sestavení dokumentace gtk-doc [výchozí je ne] --enable-gtk-doc-html: sestavit dokumentaci ve formátu HTML [výchozí je ano] --enable-gtk-doc-pdf: sestavit dokumentaci ve formátu PDF [výchozí je ne] GTK-Doc je standardně vypnuté! Nezapomeňte zadat přepínač „“ při dalším spuštění configure. Jinak se nainstaluje předgenerovaná dokumentace (která může mít význam pro uživatele, ale ne pro vývojáře). Po provedení změn v configure.ac aktualizujte soubor configure. To se dá udělat opětovným spuštěním autogen.sh. Integrace s autogen Většina projektů má skript autogen.sh, který po stažení projektu ze systému pro správu verzí (jako je Git nebo SVN), nastaví infrastrukturu pro sestavení. GTK-Doc se dodává se skriptem nazvaným gtkdocize, který lze použít ke zkopírování nezbytných souborů požadovaných GTK-Doc do zdrojové složky. Měl by být spuštěn před autoheader, automake nebo autoconf. Spuštění gtkdocize z autogen.sh gtkdocize || exit 1 Podmíněné spuštění gtkdocize z autogen.sh GTKDOCIZE=$(which gtkdocize 2>/dev/null) if test $? -ne 0; then echo "No gtk-doc support found. You can't build the docs." else $GTKDOCIZE || exit 1 fi Když spustíte gtkdocize, tak nakopíruje do kořenové složky vašeho projektu (nebo složky určené přepínačem ) soubor gtk-doc.make. gtkdocize kontroluje váš skript configure.ac ohledně makra GTK_DOC_CHECK. Toto makro můžete použít k předání dalších parametrů do skriptu gtkdocize. Konkrétně k tomu slouží druhý argument makra. Alternativně lze další argumenty skriptu gtkdocize předat přes proměnnou prostředí GTKDOCIZE_FLAGS nebo je zadat přímo za volání gtkdocize v autogen.sh. Spouštění GTK-Doc ze sestavovacího systému Po dokončení předchozích kroků nastal čas spustit sestavení. Nejdříve musíte znovu spustit autogen.sh. Pokud tento skript pro vás provádí nastavení, předejte mu přepínač . Jinak potom ručně spusťte configure s tímto přepínačem. První make spustí vygenerování několika doplňujících souborů ve složkách doc. Podstatné jsou tyto: <package>.types, <package>-docs.xml (dříve .sgml) a <package>-sections.txt. Sestavení dokumentace ./autogen.sh --enable-gtk-doc make Nyní si můžete ve svém webovém prohlížeči zobrazit docs/reference/<package>/index.html. S tímto počátečním nastavením uvidíte jen velmi jednoduchý dokument. Následující kapitola vás naučí, jak do svého zdrojového kódu přidat dokumentaci k API pomocí speciálních komentářových bloků. Dále pak kapitola seznamuje s dodatečnými soubory a ukazuje, jak upravit hlavní šablonu, abyste do svých souborů s dokumentací dostali doplňující kapitoly a oddíly. Integrace se sestavovacím systémem CMake GTK-Doc nyní nabízí modul GtkDocConfig.cmake (a příslušný modul GtkDocConfigVersion.cmake). Ten poskytuje příkaz gtk_doc_add_module, který můžete nastavit ve svém souboru CMakeLists.txt. Následující příklad ukazuje, jak tento příkaz použít: Příklad použití GTK-Doc z CMake find_package(GtkDoc 1.25 REQUIRED) # Vytvoření cíle doc-libmeep. gtk_doc_add_module( libmeep ${CMAKE_SOURCE_DIR}/libmeep XML meep-docs.xml LIBRARIES libmeep ) # Sestavení doc-libmeep jako součásti výchozího cíle. Bez tohoto byste museli # ručně spouštět něco jako `make doc-libmeep`, aby se dokumentace sestavila. add_custom_target(documentation ALL DEPENDS doc-libmeep) # Instalace dokumentace. (Předpokládá to, že používáte modul CMake GNUInstallDirs # ke správnému nastavení proměnné CMAKE_INSTALL_DOCDIR). install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html DESTINATION ${CMAKE_INSTALL_DOCDIR}) Integrace s prostými soubory Makefile nebo jinými sestavovacími systémy Když někdo nechce používat automake, a tím pádem gtk-doc.mak, bude muset volat nástroje gtkdoc ve správném pořadí ve vlastních souborech make (nebo jiných nástrojích). Kroky sestavení dokumentace DOC_MODULE=meep // sources have changed gtkdoc-scan --module=$(DOC_MODULE) <zdrojová-složka> gtkdoc-scangobj --module=$(DOC_MODULE) gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<zdrojová-složka> // xml files have changed mkdir html cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html Na výběr dalších potřebných voleb se musíte se podívat do Makefile.am a gtk-doc.mak. Integrace se systémem pro správu verzí Podle nepsaných pravidel byste soubory, které upravujete, měli udržovat ve správě verzí. U typických projektů to jsou tyto soubory: <balíček>.types, <balíček>-docs.xml (dříve .sgml), <balíček>-sections.txt a Makefile.am. Soubory ze složek xml/ a html/ by neměly být zařazeny do správy verzí. A ani žádné soubory .stamp. Dokumentování v kódu GTK-Doc používá pro kód dokumentace komentáře se speciální syntaxí ve zdrojovém kódu. K tomu se ještě získávají informace o struktuře vašeho projektu z dalších zdrojů. V následujícím oddílu najdete všechny informace o syntaxi komentářů. Skener GTK-Doc zvládá dobře většinu hlavičkových souborů C. V případě, že od něj obdržíte varování, které vypadá jako speciální případ, můžete GTK-Doc poradit, aby jej přeskakovala. Komentářový blok GTK-Doc #ifndef __GTK_DOC_IGNORE__ /* kód zde se nezpracovává */ #endif Omezení Uvědomte si, že GTK-Doc podporuje #ifndef(__GTK_DOC_IGNORE__), ale ne #if !defined(__GTK_DOC_IGNORE__) nebo jiné kombinace. Dokumentační komentáře Každý víceřádkový komentář, který je označený další „*“ navíc, je dokumentačním blokem a bude zpracovaný nástroji GTK-Doc. Komentářový blok GTK-Doc /** * identifikátor: * dokumentace … */ „identifikátor“ je jeden řádek s názvem položky, ke které se komentář vztahuje. Syntaxe se částečně liší podle položky. (DOPLNIT: přidat tabulku se seznamem identifikátorů) Blok „dokumentace“ se rovněž liší pro různé typy symbolů. Symboly, které přebírají parametry, jako jsou funkce nebo makra, mají nejdříve popsané parametry, za kterými následuje prázdný řádek (pouze „*“). Za ním pak následuje podrobný popis. Všechny řádky (mimo seznamu programů a oddílu CDATA), které obsahují „ *“ (mezera hvězdička) se převedou na zalomení odstavce. Pokud zalomení odstavce nechcete, změňte to na „ * “ (mezera hvězdička mezera mezera). To se hodí na text s pevným formátem (výpis kódu). Když píšete dokumentaci ke kódu, popište dva aspekty: Co to je: Název třídy nebo funkce může být občas matoucí pro lidi, kteří používají něco jiného. K čemu to je: Uveďte běžném použití. Dejte ho do souvislosti se zbytkem API. Jednou z výhod hypertextu, oproti prostému textu, je možnost mít v dokumentu odkazy. Zápis správných značek pro odkazy může být úmorná práce. GTK-Doc se vám snaží pomoci několika užitečnými zkratkami. Použijte funkce() pro odkaz na funkci nebo makro, které mají argumenty. Použijte @parametr pro odkaz na parametry. Použijte to rovněž, když se odkazujete na parametry jiných funkcí, vztahujících se k popisované funkci. Použijte %konstanta pro odkaz na konstantu, např. %G_TRAVERSE_LEAFS. Použijte #symbol pro odkaz na jiný typ symbolu, např. strukturu, výčet a makro, který nemá argumenty. Použijte #Objekt::signál pro odkaz na signál objektu GObject. Použijte #Objekt:vlastnost pro odkaz na vlastnost objektu GObject. Použijte #Struktura.pole pro odkaz na pole uvnitř struktury a #GObjectTřída.neco() pro odkaz na virtuální metodu. V případě, že potřebujete ve své dokumentaci použít speciální znaky „<“, „>“, „()“, „@“, „%“ nebo „#“, aniž by je GTK-Doc změnilo, můžete místo nich použít použít entity XML „&lt;“, „&gt;“, „&lpar;“, „&rpar;“, „&commat;“, „&percnt;“ a „&num;“ nebo únikovou sekvenci se zpětným lomítkem „\“. DocBook toho ale umí více, než jen odkazy. Může mít také seznamy, příklady, nadpisy a obrázky. Od verze 1.20 je dána přednost použití jen podmnožiny ze základní syntaxe formátování textu. Tato podmnožina se nazývá Markdown. Dokumentace ze starší verze GTK-Doc, která obsahuje Markdown, bude vygenerována tak, jak je. Například položky seznamu se objeví s pomlčkou na začátku. I když je markdown v současnosti preferovaný, můžete míchat oba dohromady. Má to jediné omezení v tom, že můžete použít docbook xml v markdown, ale markdown v docbook xml podporován není. Když ve starších vydáních GTK-Doc potřebujete podporu pro dodatečné formátování, musíte zapnout použití značek XML pro DocBook uvnitř dokumentačních komentářů pomocí (nebo ) v proměnné MKDB_OPTIONS v souboru Makefile.am. Komentářový blok GTK-Doc používající značkovací jazyk /** * identifikátor: * * odstavec dokumentace… * * # Podnadpis # * * ## Podnadpis druhé úrovně * * # Podnadpis s kotvou pro odkazy # {#heading-two} * * další dokumentace: * * - položka seznamu 1 * * Odstavec v rámci položky seznamu. * * - položka seznamu 2 * * 1. číslovaná položka seznamu * * 2. další číslovaná položka seznamu * * Další odstavec. [Odkazy na webové stránky GNOME](http://www.gnome.org/) * * ![vložený obrázek](plot-result.png) * * [Odkaz na nadpis pomocí kotvy uvedené výše][heading-two] * * Příklad v jazyce C: * |[<!-- language="C" --> * GtkWidget *label = gtk_label_new ("Paráda!"); * ]| */ Více příkladů k podporovaným značkám Markdown můžete najít v Referenční příručce k syntaxi Markdown pro dokumentaci GTK. Jak již bylo zmíněno dříve, slouží GTK-Doc pro dokumentování veřejného API. Tím pádem nemůžete psát dokumentaci pro statické symboly. Nicméně je vhodné komentovat i tyto symboly. Pomůže to ostatním vývojářům porozumět vašemu kódu. Proto doporučujeme komentovat je pomocí normálních komentářů (bez druhé „*“ na prvním řádku). Pokud je budete v budoucnu chtít předělat na veřejné, jediné co budete muset udělat, je přidat do komentářového bloku jednu „*“ a na správné místo v souboru oddílů vložit název symbolu. Dokumentování oddílů Každý oddíl dokumentace obsahuje informaci o jedné třídě nebo modulu. Můžete do oddílu napsat blok, ve kterém je představíte. Stručný popis se rovněž použije v rámci tabulky s obsahem. Všechna @pole jsou volitelná. Komentářový blok oddílu /** * SECTION:meepapp * @short_description: třída plikace * @title: Aplikace Meep * @section_id: * @see_also: #MeepSettings * @stability: Stable * @include: meep/app.h * @image: application.png * * Třída aplikace starající se o… */ SECTION:<název> Název prováže oddíl dokumentace s příslušnou částí v souboru <package>-sections.txt. Zde zadaný název musí odpovídat značce <SOUBOR> v souboru <package>-sections.txt. @short_description Jednořádkový popis oddílu, který se později objeví za odkazy v tabulce s obsahem a na začátku stránky oddílu. @title Název oddílu se standardně zvolí podle <name> v deklaraci SECTION. Lze jej ale určit i přímo v poli @title. @section_id Přepíše použití názvu jako identifikátoru oddílu. Pro objekty GObject se jako section_id použije <title> a pro ostatní oddíly to je <MODULE>-<title>. @see_also Seznam symbolů, které se vztahují k tomuto oddílu. @stability Informační popis úrovně stability tohoto API. Doporučujeme použít jeden z těchto termínů: Stable (stabilní) – Záměrem stabilního rozhraní je umožnit libovolné třetí straně vyvinout aplikace využívající toto rozhraní, vydat je a moci se spolehnout, že poběží na všech podružných vydáních produktu (po té, co je rozhraní vydáno a v rámci stejné hlavní verze). I mezi hlavními vydáními se nekompatibilní změny očekávají zřídka v opravdu odůvodněných případech. Unstable (nestabilní) – Nestabilní rozhraní je experimentální a přechodné. Typicky bývá dáno vývojářům k dispozici kvůli včasnému přístupu k novým a rychle se měnícím technologiím nebo kvůli poskytnutí provizorního řešení problému, kdy je předpokládané více obecné řešení. Není žádná záruka ohledně zdrojové či binární kompatibility při přechodu z jedné podružné verze na následujíc. Private (soukromé) – Rozhraní, které může být použité v rámci zásobníku GNOME, ale není dokumentované pro koncového uživatele. Takové funkce by se měly používat jen určeným a dokumentovaným způsobem. Internal (interní) – Rozhraní, které je určené pro interní potřeby modulu a nevyžaduje dokumentaci pro koncového uživatele. Funkce, které jsou nedokumentované, jsou považované za interní. @include Seznam souborů z #include oddělených čárkou, aby se zobrazily v oddílu anotace. Přepisuje globální hodnotu ze souboru oddílů nebo příkazové řádky. Tato položka je volitelná. @image Obrázek, který se má zobrazit na začátku referenční stránky k tomuto oddílu. Často se jedná o nějaký nákres, který schématicky znázorňuje podobu třídy nebo nákres se vztahy vůči jiným třídám. Tato položka je volitelná. Aby se po změně dokumentace předešlo rekompilacím, které nejsou nutné, vložte, kde je to možné, dokumentaci oddílu do zdrojového kódu c. 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. 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 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. Obecné 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) { ... Anotace Documentation blocks can contain annotation-tags. These tags will be rendered with tooltips describing their meaning. The tags are used by GObject Introspection to generate language bindings. A detailed list of the supported tags can be found in the GObject Introspection documentation. Anotace /** * 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. */ 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. Komentář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:). Komentářový blok pro vlastnost Komentářový blok pro vlastnost /** * SomeWidget:some-property: * * Zde vlastnost zdokumentujte. */ g_object_class_install_property (object_class, PROP_SOME_PROPERTY, …); 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. Komentář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[FOOBARIZED] = g_signal_new ("foobarized", ... Komentářový blok pro strukturu 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). Komentářový blok pro výčty 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 >*/. Dokumentaci k vloženým programům Programy a jejich rozhraní příkazového řádku můžete zdokumentovat pomocí vložené dokumentace. Značky PROGRAM Definuje začátek dokumentace k programu. @short_description: Definuje krátký popis programu. (volitelné) @synopsis: Definuje argumenty nebo seznam argumentů, které program přebírá. (volitelné) @see_also: Část stránky oddílu „Viz také“. (volitelné) @arg: Argument(y) předávané do programu a jejich popis. (volitelné) Description: Úplný popis programu. Returns: Specifikuje, jakou hodnotu či více hodnot program vrací. (volitelné) Příklad dokumentace k programu. Komentářový blok pro program /** * PROGRAM:test-program * @short_description: Testovací program * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE* * @see_also: test(1) * @--arg1 *arg*: nastaví arg1 do *arg* * @--arg2 *arg*: nastaví arg2 do *arg* * @-v, --version: Vypíše verzi programu * @-h, --help: Vypíše nápovědu k programu * * Úplný popis programu. * * Returns: Vrací nulu při úspěchu, nenulovou hodnotu při selhání. */ int main(int argc, char *argv[]) { return 0; } Užitečné značky DocBook Zde jsou některé značky DocBook, které mají pro dokumentaci kódu největší význam. Odkaz na jiný oddíl v dokumentaci GTK: <link linkend="glib-Hash-Tables">Hašovací tabulky</link> Odkazem je id SGML/XML v první položce stránky, na kterou chcete odkazovat. Pro většinu stránek je to v současnosti část („gtk“, „gdk“, „glib“) a potom název stránky („Hašovací tabulka“). Pro ovládací prvky je to název třídy. Mezery a podtržítka se převedou na „-“, aby to vyhovovalo SGML/XML. Odkaz na externí funkci, například standardní funkci C: <function>…</function> Vložení ukázky kódu: <example> <title>Používání GHashTable.</title> <programlisting language="C"> ... </programlisting> </example> nebo pro velmi krátké úseky kódu, které nepotřebují nadpisy, je případně možné i: <informalexample> <programlisting language="C"> ... </programlisting> </informalexample> V obou případech je atribut language volitelnáý a je používán jako rada pro program provádějící zvýrazňování syntaxe (pygments pro výstup v html).V novějších verzích GTK-Doc je také podporované zkracování: |[<!-- language="C" --> ... ]| Vložení seznamu s odrážkami: <itemizedlist> <listitem> <para> … </para> </listitem> <listitem> <para> … </para> </listitem> </itemizedlist> Vložení poznámky, která se objeví mimo text: <note> <para> Ujistěte se, že data po použití uvolníte. </para> </note> Odkaz na typ: <type>unsigned char</type> Odkaz na externí strukturu (která není popsaná v dokumentaci GTK): <structname>XFontStruct</structname> Odkaz na pole struktury: <structfield>len</structfield> Pro odkaz na název třídy by se dal nejspíše použít: <classname>GtkWidget</classname> ale pravděpodobně místo toho použijete #GtkWidget (aby se automaticky vytvořil odkaz na stránku ovládacího prvku, viz zkratky). Zvýrazněný text: <emphasis>Toto je důležité</emphasis> Pro název souboru použijte: <filename>/home/user/documents</filename> Odkaz na použití klávesy: <keycombo><keycap>Ctrl</keycap><keycap>L</keycap></keycombo> Vyplňování dodatečných souborů Mimo komentářů vložených ve zdrojovém kódu je zde ještě pár dodatečných souborů, které je potřeba udržovat:<balíček>.types, <balíček>-docs.xml (dříve .sgml) a <balíček>-sections.txt. Úprava souboru s typy Pokud vaše knihovna nebo aplikace vkládá objekty GObject, chcete jejich signály, argumenty/parametry a pozici v hierarchii ukázat v dokumentaci. Vše, co pro to potřebujete udělat, je vypsat funkce xxx_get_type spolu s jejich include v souboru <balíček>.types. Příklad souboru <balíček>.types #include <gtk/gtk.h> gtk_accel_label_get_type gtk_adjustment_get_type gtk_alignment_get_type gtk_arrow_get_type Od GTK-Doc verze 1.8 vám tento seznam vygeneruje gtkdoc-scan. Stačí jen přidat „--rebuild-types“ do SCAN_OPTIONS v Makefile.am. Pokud tento přístup použijete, neměli byste soubor s typy šířit do správy verzí. Úprava hlavního dokumentu GTK-Doc produkuje dokumentaci v SGML/XML standardu DocBook. Když se zpracovávají komentáře vložené ve zdrojovém kódu, generují nástroje GTK-Doc pro každou třídu nebo modul jednu stránku dokumentace jako samostatný soubor. Všechny jsou pak uvedené seřazené v hlavním dokumentu. Jakmile pro vás GTK-Doc vytvoří šablonu hlavního dokumentu, při pozdějším spuštění již do ní nezasahuje. To znamená, že můžete dokumentaci bez omezení strukturovat. A to včetně seskupování stránek a přidávání doplňujících stránek. GTK-Doc má v současnosti testovací sadu, ve které je také hlavní dokument vytvořen znovu od začátku. Je dobré se čas od času do něj nahlédnout, jestli se v něm neobjevily nějaké nové věci. Nevytvářejte výukové dokumenty (tutorial) jako zvláštní dokumenty. Napište je jako zvláštní kapitolu. Výhodou přímého spojení výukového dokumentu k vaší knihovně s dokumentací API je snadné vytváření odkazů pro symboly. Zvyšuje se tím také šance, že výukový dokument bude reflektovat aktualizace v knihovně. Nyní se podívejme, které věci můžete v hlavním dokumentu měnit. Pro začátek je to pouze název. Je zde několik zástupných hodnot (text v hranatých závorkách), o které byste se měli postarat. Hlavička hlavního dokumentu <bookinfo> <title>Referenční příručka k NÁZEV_MODULU</title> <releaseinfo> pro NÁZEV_MODULU [VERSION] Nejvnovější verzi tohoto dokumentu můžete najít on-line na <ulink role="online-location" url="http://[SERVER]/NÁZEV_MODULU/index.html">http://[SERVER]/NÁZEV_MODULU/</ulink>. </releaseinfo> </bookinfo> <chapter> <title>[Insert title here]</title> Navíc se vytvoří pár volitelných prvků ve formě komentáře. Můžete si je projít a případně povolit. Volitelná část hlavního dokumentu <!-- enable this when you use gobject introspection annotations <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include> --> Nakonec musíte přidat nový oddíl, kdekoliv chcete. Nástroj gtkdoc-check vás upozorní na nově vygenerované soubory XML, které zatím nejsou v dokumentaci zahrnuté. Vkládání generovaných oddílů <chapter> <title>moje knihovna</title> <xi:include href="xml/object.xml"/> … Úprava souboru oddílů Soubor oddílů se používá k organizování výstupu dokumentace z GTK-Doc. Zde se určuje, který symbol náleží ke kterému modulu nebo třídě, a řídí se viditelnost (jestli je veřejný nebo soukromý). Soubor oddílů je prostý textový soubor, ve kterém jsou oddíly oddělené značkami. Prázdné řádky se ignorují a s řádky začínajícími „#“ se zachází jako s komentářovými řádky. Přestože díky značkám vypadá soubor podobně jako XML, není tomu tak. Neuzavírejte prosím značky jako je <SUBSECTION>. Vkládání generovaných oddílů <INCLUDE>libmeep/meep.h</INCLUDE> <SECTION> <FILE>meepapp</FILE> <TITLE>MeepApp</TITLE> MeepApp <SUBSECTION Standard> MEEP_APP ... MeepAppClass meep_app_get_type </SECTION> Značka <FILE> … </FILE> se používá k určení názvu souboru bez přípony. Například použití „<FILE>gnome-config</FILE>“ bude mít v deklaracích oddílu za následek výstup do souboru šablony tmpl/gnome-config.sgml, který bude převeden do souboru sgml/gnome-config.sgml ve formátu DocBook SGML nebo do souboru xml/gnome-config.xml ve formátu DocBook XML. (Název souboru HTML vychází z názvu modulu a názvu oddílu, případně pro GObject z názvu třídy GObject převedeného na malá písmena.) Značka <TITLE> … </TITLE> se používá k určení názvu oddílu. To je použitelné pouze dříve, než je poprvé vytvořena šablona (pokud se používá), protože název nastavený v šabloně tento název přepíše. Navíc je považována za zastaralou v případě, že se používá komentář SECTION ve zdrojovém kódu. Můžete také seskupovat položky v oddílu pomocí značky <SUBSECTION>. V současnosti způsobí prázdný řádek mezi pododdíly v souhrnné části. Můžete také použít <SUBSECTION Standard> pro standardní deklarace GObject (například funkce jako je g_object_get_type, makra jako G_OBJECT(), G_IS_OBJECT() atd.). V současnosti jsou tyto v dokumentaci vynechané. Můžete také použít <SUBSECTION Private> pro privátní deklarace, které ve výsledku nebudou (jedná se o ruční způsob, jak zabránit varovným hlášením o nepoužitých deklaracích). Pokud vaše knihovna obsahuje privátní typy, u kterých nechcete, aby se objevily v hierarchii objektů a v seznamu implementovaných nebo vyžadovaných rozhraní, přidejte je do pododdílu Private. Jestli umístit struktury jako GObject a GObjectClass do veřejné nebo standardní části záleží na tom, jestli mají veřejné položky (proměnné, virtuální metody). Můžete také použít <INCLUDE> ... </INCLUDE> k určení #include souborů, které jsou zobrazené v souhrnné části. Obsahuje čárkami oddělený seznam jednotlivých #include souborů, bez lomených závorek. Když je nastavíte mimo kterýkoliv oddíl, budou fungovat pro všechny oddíly až do konce souboru. Když je nastavíte v konkrétním oddílu, použijí se jen pro něj. Ovlivnění výsledku Spuštění GTK-Doc vygeneruje ve složkách pro dokumentaci soubory s výstupními sestavami. Generované soubory jsou nazvané: <balíček>-undocumented.txt, <balíček>-undeclared.txt a <balíček>-unused.txt. Všechno to jsou prosté textové soubory, které si lze jednoduše prohlížet a zpracovávat je. Soubor <balíček>-undocumented.txt začíná souhrnnými údaji o dokumentaci. Následují dva oddíly oddělené prázdnými řádky. První oddíl je seznam nezdokumentovaných nebo neúplných symbolů. Druhý oddíl je to stejné, ale pro dokumentace oddílů. Neúplné položky jsou takové, které mají dokumentaci, ale u kterých byl například přidán nový parametr. Soubor <balíček>-undeclared.txt uvádí symboly, které jsou zadané v <balíček>-section.txt, ale nebyly nalezené ve zdrojových kódech. Ověřte, jestli nebyly odstraněny, nebo v nich není překlep. Soubor <balíček>-unused.txt uvádí názvy symbolů, které GTK-Doc při procházení dokumentace nalezl, ale neví, kam je zařadit. To znamená, že tyto symboly nejsou zatím zařazené v souboru <balíček>-section.txt. Povolte nebo přidejte řádek v Makefile.am. Pokud máte nainstalované GTK-Doc ve verzi minimálně 1.9, bude se díky tomu při spuštění make check provádět kontrola správnosti údajů. Můžete se také podívat do souborů vytvořených skenerem zdrojového kódu: <package>-decl-list.txt a <package>-decl.txt. První můžete porovnat se souborem s oddíly, pokud je ručně spravován. Ve druhém jsou uvedené všechny deklarace z hlavičkových souborů. Pokud v dokumentaci schází některý symbol, můžete zkontrolovat, jestli se vyskytuje v tomto souboru. Pokud je základem projektu GObject, můžete se také podívat do souborů vytvořených skenerem objektů: <package>.args.txt, <package>.hierarchy.txt, <package>.interfaces.txt, <package>.prerequisites.txt a <package>.signals.txt. Jestliže v kterémkoliv z nich jsou chybějící symboly, můžete spuštěním GTK_DOC_KEEP_INTERMEDIATE=1 make požádat GTK-Doc, aby přechodně zachovat soubor pro pozdější analýzu. Modernizace dokumentu GTK-Doc existuje již nějakou dobu. V této části je uveden seznam nových funkcí spolu s číslem verze, od které je tato funkčnost k dispozici. GTK-Doc 1.9 Když používáte XML namísto SGML, můžete ve skutečnosti pojmenovat hlavní dokument <package>-docs.xml. Tato verze podporuje v Makefile.am. Když je tato volba zapnutá, je <package>-sections.txt generován automaticky a můžete jej odstranit ze správy verzí. To funguje hezky je u projektů, které mají pravidelnou strukturu (například jednotlivé páry souboru .c a .h vytvoří nový oddíl). Pokud máte projekt takto pečlivě organizovaný, vystačí si aktualizace ručně spravovaného souboru s oddíly s prostým spuštěním meld <package>-decl-list.txt <package>-sections.txt. Již verze 1.18 zavedla syntax pro dokumentování oddílů ve zdrojovém kódu namísto zvláštních souborů ve složce tmpl. Tato verze přidává pomocí in configure.ac volbu pro přepnutí celého modulu dokumentace, aby nepoužíval speciální složku tmp během sestavení. Jestliže nepotřebujete udržovat tmpl v systému pro správu verzí ještě jste zatím přepnutí neprovedli, stačí přidat tuto volbu do configure.ac a je to. GTK-Doc 1.10 Tato verze podporuje v Makefile.am. Když je tato volba zapnutá, je <package>.types generován automaticky a můžete jej odstranit ze správy verzí. Jestliže tuto funkci využíváte, je důležité nastavit také IGNORE_HFILES v Makefile.am pro kód, který je sestavován podmíněně. GTK-Doc 1.16 Součástí této verze je nový nástroj s názvem gtkdoc-check. Jeho spuštěním se provede kontrola správnosti vašeho dokumentu. Povolit jej můžete přidáním těchto řádků na konec souboru Makefile.am. Povolení gtkdoc-check if ENABLE_GTK_DOC TESTS_ENVIRONMENT = \ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir) TESTS = $(GTKDOC_CHECK) endif GTK-Doc 1.20 Verze 1.18 přinesla počáteční podporu pro Markdown. Jeho použití v dokumentačních komentářích je méně rušivé, než zápis XML z DocBook. Tato verze jeho podporu značně vylepšuje a přidává mnohem více stylů. Více podrobností je uvedeno v oddílu, který vysvětluje syntax komentářů. GTK-Doc 1.25 Soubory Makefile dodávané s touto verzí generují do xml/gtkdocentities.ent soubor s entitami, který obsahuje entity například pro package_name a package_version. Můžete je použít třeba v hlavním souboru XML, abyste nemuseli mít číslo verze zapsané natvrdo. Níže je uveden příklad, jak soubor s entitami vložit do hlavní šablony a jak entity použít. Použít je lze také ve všech generovaných souborech, GTK-Doc bude používat tu samou hlavičku XML v generovaných souborech XML. Používání předgenerovaných entit <?xml version="1.0"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'"> <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent"> %gtkdocentities; ]> <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> <bookinfo> <title>&Referenční příručka k package_name;</title> <releaseinfo> for &package_string;. Nejnovější verzi této dokumentace můžete najít on-line na <ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>. </releaseinfo> </bookinfo> Dokumentování ostatních rozhraní Doposud jsme pomocí GTK-Doc dokumentovali API kódu. Následující oddíl obsahuje doporučení, jak se dají nástroje použít také k dokumentování dalších rozhraní. Přepínače příkazového řádku a manuálové stránky Protože je stejně možné generovat manuálové stránky pro referenční položky DocBook, zní jako dobrý nápad použít to pro tento účel. Tímto způsobem se rozhraní stane součástí referenční příručky a získáte tak bez námahy manuálovou stránku. Dokumentování nástrojů Vytvořte jeden soubor s referenční příručkou pro každý z nástrojů. V našem příkladu by se měl nazývat meep/docs/reference/meeper/meep.xml. Na značky XML, který by se měly použít, se podívejte do nějakého ukázkového vygenerovaného souboru v podsložce XML, například v glib. Přidání doplňkových kontrol do configure Dodatečné kontroly nastavení AC_ARG_ENABLE(man, [AC_HELP_STRING([--enable-man], [regenerate man pages from Docbook [default=no]])],enable_man=yes, enable_man=no) AC_PATH_PROG([XSLTPROC], [xsltproc]) AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno) Přidání doplňkových pravidel do Makefile Dodatečné kontroly nastavení man_MANS = \ meeper.1 if ENABLE_GTK_DOC if ENABLE_MAN %.1 : %.xml @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $< endif endif BUILT_EXTRA_DIST = $(man_MANS) EXTRA_DIST += meep.xml Rozhraní D-Bus (OPRAVIT: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus) Často kladené dotazy Dotaz Odpověď Schází hierarchie třídy. Do souboru <balíček>.types nebyla vložena funkce objektu xxx_get_type(). Stále schází hierarchie třídy. Chybějící nebo nesprávné pojmenování souboru <balíček>-sections.txt (viz vysvětlení). Do háje, pořád nemám hierarchii třídy. Je název objektu (název struktury instance, například GtkWidget) součástí normálního oddílu? (Nedávejte je do pododdílu Standard nebo Private). Chybí rejstřík symbolů. Obsahuje <package>-docs.{xml,sgml} rejstřík, který vloží pomocí xi:include vygenerovaný rejstřík? Symbol nemá odkaz do svého oddílu dokumentace. Používá dokumentační komentář správnou značku (přidané znaky #,% nebo ())? Podívejte se na varování gtkdoc-fixxref o nevyřešených křížových odkazech. Nová třída se neobjevila v dokumentaci. Je nový balíček vložený pomocí xi:include z <package>-docs.{xml,sgml}. Nový symbol se neobjevil v dokumentaci. Je dokumentační komentář správně naformátovaný? Zkontrolujte překlepy na začátku komentáře. Podívejte se po varováních gtkdoc-fixxref o nevyřešených křížových odkazech. Zkontrolujte, jestli je symbol správně uvedený v <package>-sections.txt ve veřejném pododdíle. V hierarchii třídy schází typ. Jestliže je typ uvedený v <package>.hierarchy, ale není v xml/tree_index.sgml, tak raději dvakrát zkontrolujte, jestli je typ správně uvedený v <package>-sections.txt. Jestliže instance typu (například GtkWidget) není uvedená, nebo je nedopatřením označení jako privátní, nebude zobrazena. Vytvořily se mi odkazy na složku s dokumentací pro všechny anotace k GObject Zkontrolujte, že xml/annotation-glossary.xml je vložené pomocí xi:include z <package>-docs.{xml,sgml}. Parametr je v komentářovém bloku zdrojového kódu popsaný, ale neexistuje. Zkontrolujte, za nemá prototyp v hlavičkovém souboru jiné názvy parametrů, než ve zdrojovém kódu. Více „ID“ pro tentýž cíl odkazu: XYZ Symbol XYZ se v souboru <package>-sections.txt objevuje dvakrát. Element typename ve jmenném prostoru '' je uvedený v rodiči, ale neodpovídá mu žádná šablona. Nástroje související s GTK-Doc GtkDocPlugin – zásuvný modul pro integraci GTK-Doc do systému Track, který přidává dokumentaci k API na sledovací web a integruje ji do vyhledávání. Gtkdoc-depscan – nástroj (součást GTK-Doc), který kontroluje použité API vůči štítku since v API, aby určil minimální požadovanou verzi. Verze 1.1, březen 2000 2000Free Software Foundation, Inc.
Free Software Foundation, Inc. 51 Franklin Street, Suite 330, Boston, MA 02110-1301 USA
Kdokoliv je oprávněn kopírovat a šířit doslovné kopie tohoto dokumentu s licencí, ale nesmí v něm provádět žádné změny. GNU Free Documentation License 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other written document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of copyleft, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The Document, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as you. A Modified Version of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A Secondary Section is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The Invariant Sections are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. The Cover Texts are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Transparent copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not Transparent is called Opaque. Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only. The Title Page means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, Title Page means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: A Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five). C State on the Title Page the name of the publisher of the Modified Version, as the publisher. D Preserve all the copyright notices of the Document. E Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. F Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. G Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. H Include an unaltered copy of this License. I Preserve the section entitled History, and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled History in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. J Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the History section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K In any section entitled Acknowledgements or Dedications, preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M Delete any section entitled Endorsements. Such a section may not be included in the Modified Version. N Do not retitle any existing section as Endorsements or to conflict in title with any Invariant Section. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section entitled Endorsements, provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version . 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections entitled History in the various original documents, forming one section entitled History; likewise combine any sections entitled Acknowledgements, and any sections entitled Dedications. You must delete all sections entitled Endorsements. 6. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. 7. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an aggregate, and this License does not apply to the other self-contained works thus compiled with the Document , on account of their being thus compiled, if they are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate. 8. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail. 9. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 10. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License or any later version applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. Addendum To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled GNU Free Documentation License.
If you have no Invariant Sections, write with no Invariant Sections instead of saying which ones are invariant. If you have no Front-Cover Texts, write no Front-Cover Texts instead of Front-Cover Texts being LIST; likewise for Back-Cover Texts. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.