Use gtk-doc with up-to-date settings for API documentation. ()
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
Add introspection annotations to all API documentation. ()
Add Since lines to all API documentation.
()
Test mit gtk-doc aktivieren. ()
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.
To integrate gtk-doc into a project’s build system, follow the
instructions in the gtk-doc manual. Note that while the
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
@PACKAGE_VERSION@
Fügen Sie sie zu AC_CONFIG_FILES in <!ENTITY version SYSTEM "version.xml"> in the DOCTYPE am Anfang des Dokuments. Die Paketversion kann dann als &version; in den Text eingebettet werden.
Wenn Sie ein Standard-Layout für das Inhaltsverzeichnis, die Abschnitte, Anhänge usw. verwenden, können Sie die gleiche
Das folgende Layout ist zu empfehlen:
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
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
To properly document a new class, it needs to be given its own
section in get_type() function for your class needs
to be listed in your
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.
*/
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 introspection guidelines.
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
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
<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 interface descriptions contain documentation comments, and these can
be extracted from the XML using
Die DocBook-Dateien können folgendermaßen in die Datei
<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 builddir does
not equal the srcdir.)
gtk-doc comes with support for checking the documentation with some basic
tests. These check that all version indexes are included in the main
Diese Tests sollten immer aktiviert werden. Fügen Sie Folgendes zu
TESTS = $(GTKDOC_CHECK)
Die Tests werden dann innerhalb von