Federico Mena-Quintero
federico@gnome.org 2013
Philip Withnall
philip.withnall@collabora.co.uk 2015
Das GTK+-Team
Dokumentation zu Bibliotheken und APIs hinzufügen
Mario Blättermann
mario.blaettermann@gmail.com 2016, 2018
Christian Kirbach
christian.kirbach@gmail.com 2016
Stefan Melmuk
stefan.melmuk@gmail.com 2018

# Dokumentation

#

        Zusammenfassung

          Verwenden Sie gtk-doc mit aktuellen Einstellungen für API-Dokumentation. ()

            Use XML entities for including external symbols into the documentation.
            ()

            Use a consistent, standard, table of contents for all API documentation
            to maintain familiarity. ()

            Use gdbus-codegen to generate D-Bus API documentation to
            include in the gtk-doc build. ()

            Add introspection annotations to all API documentation.
            ()

            Add Since lines to all API documentation.
            ()

          Test mit gtk-doc aktivieren. ()

# gtk-doc

Das bevorzugte Dokumentationssystem für GNOME-Bibliotheken ist gtk-doc, welches eingebettete Kommentare aus dem Code entpackt und daraus ein DocBook-Dokument und HTML-Seiten erstellen kann. Diese können in Devhelp gelesen werden. Ein großer Teil der Infrastruktur von GNOME ist darauf ausgelegt, mit Dokumentation umzugehen, die mit gtk-doc erstellt wurde.

# Build-System

To integrate gtk-doc into a project’s build system, follow the instructions in the gtk-doc manual. Note that while the sections.txt 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 in version control.

gtk-doc’s `no-tmpl` flavour should be used, and XML mode should be used instead of SGML. (tmpl mode and SGML are both outdated and slower than XML.)

Falls es nötig ist, die Paketversion in der Dokumentation anzupassen, erstellen Sie eine Datei namens docs/version.xml.in, die Folgendes enthält:

@PACKAGE_VERSION@

Fügen Sie sie zu `AC_CONFIG_FILES` in configure.ac hinzu und schließen Sie sie folgendermaßen in die Haupt-Dokumentationsdatei (*-docs.xml) ein: `<!ENTITY version SYSTEM "version.xml">` in the `DOCTYPE` am Anfang des Dokuments. Die Paketversion kann dann als `&version;` in den Text eingebettet werden.

# Standard-Layout

Wenn Sie ein Standard-Layout für das Inhaltsverzeichnis, die Abschnitte, Anhänge usw. verwenden, können Sie die gleiche Projektname-docs.xml-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.

Das folgende Layout ist zu empfehlen:

## Projektname-docs.xml

Vorlage für eine gtk-doc-Datei der obersten Ebene

# Lizenzierung

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.

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.

As shown in the Standard Layout you should include a license.xml in the top-level gtk-doc DocBook file which gives the full text of your documentation license.

# Öffentliche APIs

Alle öffentlichen APIS müssen gtk-doc-Kommentare haben. Für Funktionen sollten diese in der Quelldatei direkt über der Funktion platziert werden.

/** * 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) {

...

}

Documentation comments for macros, function types, class structs, etc. should be placed next to the definitions, typically in header files.

Section introductions should be placed in the source file they describe, after the license header:

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

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 modulename-sections.txt file.

To properly document a new class, it needs to be given its own section in modulename-sections.txt, needs to be included in your toplevel modulename-docs.sgml, and the `get_type()` function for your class needs to be listed in your modulename.types.

# Introspection Annotations

Each gtk-doc comment should have appropriate GObject introspection annotations. These are useful for two reasons:

They add important information about parameter types, nullability and memory management to the C API documentation generated by gtk-doc.

They allow public APIs to be automatically bound in other languages, such as Python or JavaScript.

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.

In gtk-doc comments, annotations should be preferred over human-readable equivalents. For example, when documenting a function parameter which may be `NULL`, use the `(nullable)` annotation rather than some text:

/** * my_function: * @parameter: (nullable): some parameter which affects something * * Body of the function documentation. */

Anstelle von:

/** * my_bad_function: * @parameter: some parameter which affects something, or %NULL to ignore * * Bad body of the function documentation. */

For more information on introspection, see the introspection guidelines.

# Symbol-Versionierung

Whenever a symbol is added to the public API, it should have a documentation comment added. This comment should always contain a `Since` line with the package version number of the release which will first contain the new API. This should be the number currently in configure.ac if post-release version incrementing is being used.

Zum Beispiel:

/** * my_function: * @param: some parameter * * Body of the function documentation. * * Since: 0.5.0 */

gtk-doc uses this information to generate indexes of the APIs added in each release. These should be added to the main *-docs.xml as an appendix:

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

# D-Bus-APIs

D-Bus interface descriptions contain documentation comments, and these can be extracted from the XML using gdbus-codegen, and turned into DocBook files to be included by gtk-doc.

Die DocBook-Dateien können folgendermaßen in die Datei *-docs.xml eingeschlossen werden:

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

The generated XML files must be included in the `content_files` variable in your gtk-doc Makefile.am, otherwise the build will fail. (This is to fix situations where the `builddir` does not equal the `srcdir`.)

# Dekumentation aktuell halten

gtk-doc comes with support for checking the documentation with some basic tests. These check that all version indexes are included in the main *-docs.xml file and that all symbols are documented, among other things.

Diese Tests sollten immer aktiviert werden. Fügen Sie Folgendes zu Makefile.am für gtk-doc hinzu:

TESTS = $(GTKDOC_CHECK)

Die Tests werden dann innerhalb von make check ausgeführt.