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
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. ()
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.
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
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
@PACKAGE_VERSION@
Přidejte jej do AC_CONFIG_FILES v <!ENTITY version SYSTEM "version.xml"> v DOCTYPE na začátku dokumentu. Verzi balíčku pak můžete vkládat pomocí &version;.
Použití standardního uspořádání pro obsah, oddíly, dodatky atd. znamená, že stejnou šablonu
Je doporučováno následující uspořádá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
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
Správné zdokumentování nové třídy vyžaduje poskytnutí jejího vlastního oddílu v get_type() pro vaši třídu musí být uvedená v
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.
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
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
<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>
Popisy rozhraní D-Bus obsahují dokumentační komentáře a ty je možné získat z XML pomocí
Soubory DocBook mohou být vloženy do souboru
<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 builddir není shodná se srcdir.)
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
Tyto testy by měly být vždy povolené přidáním následujícího do
TESTS = $(GTKDOC_CHECK)
Budou pak spouštěny jako součást