<?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="de">
<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>Das GTK+-Team</name>
</credit>
<include xmlns="http://www.w3.org/2001/XInclude" href="cc-by-sa-3-0.xml"/>
<desc>Dokumentation zu Bibliotheken und APIs hinzufügen</desc>
<mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
<mal:name>Mario Blättermann</mal:name>
<mal:email>mario.blaettermann@gmail.com</mal:email>
<mal:years>2016</mal:years>
</mal:credit>
<mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
<mal:name>Christian Kirbach</mal:name>
<mal:email>christian.kirbach@gmail.com</mal:email>
<mal:years>2016</mal:years>
</mal:credit>
</info>
<title>Dokumentation</title>
<synopsis>
<title>Zusammenfassung</title>
<list>
<item><p>
Use gtk-doc with up-to-date settings for API documentation.
(<link xref="#gtk-doc"/>)
</p></item>
<item><p>
Use XML entities for including external symbols into the documentation.
(<link xref="#build-system"/>)
</p></item>
<item><p>
Use a consistent, standard, table of contents for all API documentation
to maintain familiarity. (<link xref="#standard-layout"/>)
</p></item>
<item><p>
Use <cmd>gdbus-codegen</cmd> to generate D-Bus API documentation to
include in the gtk-doc build. (<link xref="#dbus-api"/>)
</p></item>
<item><p>
Add introspection annotations to all API documentation.
(<link xref="#introspection-annotations"/>)
</p></item>
<item><p>
Add <code>Since</code> lines to all API documentation.
(<link xref="#symbol-versioning"/>)
</p></item>
<item><p>Test mit gtk-doc aktivieren. (<link xref="#keeping-up-to-date"/>)</p></item>
</list>
</synopsis>
<section id="gtk-doc">
<title>gtk-doc</title>
<p>Das bevorzugte Dokumentationssystem für GNOME-Bibliotheken ist <link href="http://www.gtk.org/gtk-doc/">gtk-doc</link>, welches eingebettete Kommentare aus dem Code entpackt und daraus ein <link href="http://docbook.org/">DocBook</link>-Dokument und HTML-Seiten erstellen kann. Diese können in <link href="https://wiki.gnome.org/Apps/Devhelp">Devhelp</link> gelesen werden. Ein großer Teil der Infrastruktur von GNOME ist darauf ausgelegt, mit Dokumentation umzugehen, die mit gtk-doc erstellt wurde.</p>
</section>
<section id="build-system">
<title>Build-System</title>
<p>
To integrate gtk-doc into a project’s build system, follow the
<link href="https://developer.gnome.org/gtk-doc-manual/stable/settingup.html.en">
instructions in the gtk-doc manual</link>. Note that while the
<file>sections.txt</file> file is automatically generated the first time
gtk-doc is run, it is not generated subsequently, and should be kept up to
date manually. It should also be
<link href="https://developer.gnome.org/gtk-doc-manual/stable/settingup_vcs.html.en">
in version control</link>.
</p>
<p>
gtk-doc’s <code>no-tmpl</code> flavour should be used, and XML mode should
be used instead of SGML. (tmpl mode and SGML are both outdated and slower
than XML.)
</p>
<p>Falls es nötig ist, die Paketversion in der Dokumentation anzupassen, erstellen Sie eine Datei namens <file>docs/version.xml.in</file>, die Folgendes enthält:</p>
<code>@PACKAGE_VERSION@</code>
<p>Fügen Sie sie zu <code>AC_CONFIG_FILES</code> in <file>configure.ac</file> hinzu und schließen Sie sie folgendermaßen in die Haupt-Dokumentationsdatei (<file>*-docs.xml</file>) ein: <code><!ENTITY version SYSTEM "version.xml"></code> in the <code>DOCTYPE</code> am Anfang des Dokuments. Die Paketversion kann dann als <code>&version;</code> in den Text eingebettet werden.</p>
</section>
<section id="standard-layout">
<title>Standard-Layout</title>
<p>Wenn Sie ein Standard-Layout für das Inhaltsverzeichnis, die Abschnitte, Anhänge usw. verwenden, können Sie die gleiche <file><var>Projektname</var>-docs.xml</file>-Vorlage mit wenigen Änderungen für andere Projekte verwenden. Es hat auch den Effekt, dass das Dokumentationslayout über Projektgrenzen hinweg gleich ist und dadurch den Entwicklern mehr vertraut ist.</p>
<p>Das folgende Layout ist zu empfehlen:</p>
<listing>
<title><file><var>Projektname</var>-docs.xml</file></title>
<desc>Vorlage für eine gtk-doc-Datei der obersten Ebene</desc>
<code mime="application/docbook+xml"><xi:include href="example-docs.xml" parse="text"/></code>
</listing>
</section>
<section id="licensing">
<title>Lizenzierung</title>
<p>Es ist wichtig, die für die API-Referenzen verwendete Lizenz klar zu stellen, insbesondere dann, wenn der Code Beispiele enthält, die frei kopiert werden dürfen.</p>
<p>Typischerweise verwenden Projekte meist die gleiche Lizenz für ihre API-Referenzen wie für den Projektcode selbst, um Verwirrung zu vermeiden. Andere Projekte verwenden CC-BY-SA 3.0 für sämtliche Referenzdokumentation. Die Wahl liegt bei Ihnen.</p>
<p>
As shown in the <link xref="#standard-layout">Standard Layout</link> you
should include a <file>license.xml</file> in the top-level gtk-doc DocBook
file which gives the full text of your documentation license.
</p>
</section>
<section id="public-api">
<title>Public APIs</title>
<p>
All public APIs must have gtk-doc comments. For functions, these should
be placed in the source file, directly above the function.
</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>
Documentation comments for macros, function types, class
structs, etc. should be placed next to the definitions, typically
in header files.
</p>
<p>
Section introductions should be placed in the source file they describe,
after the license header:
</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>
Keep in mind that in order to include a function, macro,
function type, or struct type, it needs to be listed in your
documentation’s <file>modulename-sections.txt</file> file.
</p>
<p>
To properly document a new class, it needs to be given its own
section in <file>modulename-sections.txt</file>, needs to be
included in your toplevel <file>modulename-docs.sgml</file>,
and the <code>get_type()</code> function for your class needs
to be listed in your <file>modulename.types</file>.
</p>
</section>
<section id="introspection-annotations">
<title>Introspection Annotations</title>
<p>
Each gtk-doc comment should have appropriate
<link href="https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations">
GObject introspection annotations</link>. These are useful for two
reasons:
</p>
<list type="numbered">
<item><p>
They add important information about parameter types, nullability and
memory management to the C API documentation generated by gtk-doc.
</p></item>
<item><p>
They allow public APIs to be automatically bound in other languages,
such as Python or JavaScript.
</p></item>
</list>
<p>
Introspection annotations add information to APIs (functions, function
parameters, function return values, structures, GObject properties,
GObject signals) which is otherwise not present in the machine readable C
API and only exists in the form of human readable documentation or
convention. They are very important.
</p>
<p>
In gtk-doc comments, annotations should be preferred over human-readable
equivalents. For example, when documenting a function parameter which may
be <code>NULL</code>, use the <code>(nullable)</code> annotation rather
than some text:
</p>
<code mime="text/x-csrc" style="valid">/**
* my_function:
* @parameter: (nullable): some parameter which affects something
*
* Body of the function documentation.
*/</code>
<p>
Instead of:
</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>
For more information on introspection, see the
<link xref="introspection">introspection guidelines</link>.
</p>
</section>
<section id="symbol-versioning">
<title>Symbol Versioning</title>
<p>
Whenever a symbol is added to the public API, it should have a
documentation comment added. This comment should always contain a
<code>Since</code> line with the package version number of the release
which will first contain the new API. This should be the number currently
in <file>configure.ac</file> if
<link xref="versioning#release-process">post-release version
incrementing</link> is being used.
</p>
<p>Zum Beispiel:</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 uses this information to generate indexes of the APIs added in
each release. These should be added to the main <file>*-docs.xml</file> as
an appendix:
</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>D-Bus-APIs</title>
<p>
D-Bus interface descriptions contain documentation comments, and these can
be extracted from the XML using <cmd>gdbus-codegen</cmd>, and turned into
DocBook files to be included by gtk-doc.
</p>
<p>Die DocBook-Dateien können folgendermaßen in die Datei <file>*-docs.xml</file> eingeschlossen werden:</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>
The generated XML files must be included in the <code>content_files</code>
variable in your gtk-doc <file>Makefile.am</file>, otherwise the build
will fail. (This is to fix situations where the <code>builddir</code> does
not equal the <code>srcdir</code>.)
</p>
</section>
<section id="keeping-up-to-date">
<title>Dekumentation aktuell halten</title>
<p>
gtk-doc comes with support for checking the documentation with some basic
tests. These check that all version indexes are included in the main
<file>*-docs.xml</file> file and that all symbols are documented, among
other things.
</p>
<p>Diese Tests sollten immer aktiviert werden. Fügen Sie Folgendes zu <file>Makefile.am</file> für gtk-doc hinzu:</p>
<code>TESTS = $(GTKDOC_CHECK)</code>
<p>Die Tests werden dann innerhalb von <cmd>make check</cmd> ausgeführt.</p>
</section>
</page>