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

        Use gtk-doc with up-to-date settings for API documentation.

        (<link xref="#gtk-doc"/>)

      
</item>

      <item>

        Use XML entities for including external symbols into the documentation.

        (<link xref="#build-system"/>)

      
</item>

      <item>

        Use a consistent, standard, table of contents for all API documentation

        to maintain familiarity. (<link xref="#standard-layout"/>)

      
</item>

      <item>

        Use <cmd>gdbus-codegen</cmd> to generate D-Bus API documentation to

        include in the gtk-doc build. (<link xref="#dbus-api"/>)

      
</item>

      <item>

        Add introspection annotations to all API documentation.

        (<link xref="#introspection-annotations"/>)

      
</item>

      <item>

        Add Since lines to all API documentation.

        (<link xref="#symbol-versioning"/>)

      
</item>

      <item>
Test mit gtk-doc aktivieren. (<link xref="#keeping-up-to-date"/>)
</item>

    </list>

  </synopsis>

  <section id="gtk-doc">

    <title>gtk-doc</title>

    
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.

  </section>

  <section id="build-system">

    <title>Build-System</title>

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

      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 <file>docs/version.xml.in</file>, die Folgendes enthält:

    @PACKAGE_VERSION@

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

  </section>

  <section id="standard-layout">

    <title>Standard-Layout</title>

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

    
Das folgende Layout ist zu empfehlen:

    <listing>

      <title><file>Projektname-docs.xml</file></title>

      <desc>Vorlage für eine gtk-doc-Datei der obersten Ebene</desc>

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

    </listing>

  </section>

  <section id="licensing">

    <title>Lizenzierung</title>

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

  </section>

  <section id="public-api">

    <title>Public APIs</title>

      All public APIs must have gtk-doc comments. For functions, these should

      be placed in the source file, directly above the function.

    /**

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

      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 get_type() function for your class needs

      to be listed in your <file>modulename.types</file>.

  </section>

  <section id="introspection-annotations">

    <title>Introspection Annotations</title>

      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:

    <list type="numbered">

      <item>

        They add important information about parameter types, nullability and

        memory management to the C API documentation generated by gtk-doc.

      
</item>

      <item>

        They allow public APIs to be automatically bound in other languages,

        such as Python or JavaScript.

      
</item>

    </list>

      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.

 */

      Instead of:

    /**

 * 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

      <link xref="introspection">introspection guidelines</link>.

  </section>

  <section id="symbol-versioning">

    <title>Symbol Versioning</title>

      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 <file>configure.ac</file> if

      <link xref="versioning#release-process">post-release version

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

  </section>

  <section id="dbus-api">

    <title>D-Bus-APIs</title>

      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.

    
Die DocBook-Dateien können folgendermaßen in die Datei <file>*-docs.xml</file> 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 <file>Makefile.am</file>, otherwise the build

      will fail. (This is to fix situations where the builddir does

      not equal the srcdir.)

  </section>

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

    <title>Dekumentation aktuell halten</title>

      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.

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

    TESTS = $(GTKDOC_CHECK)

    
Die Tests werden dann innerhalb von <cmd>make check</cmd> ausgeführt.

  </section>

</page>