- Use gtk-doc with up-to-date settings for API documentation. (gtk-doc)
- Use XML entities for including external symbols into the documentation. (Build system)
- Use a consistent, standard, table of contents for all API documentation to maintain familiarity. (Standard layout)
gdbus-codegento generate D-Bus API documentation to include in the gtk-doc build. (D-Bus APIs)
- Add introspection annotations to all API documentation. (Introspection annotations)
Sincelines to all API documentation. (Symbol versioning)
- Enable gtk-doc tests. (Keeping documentation up to date)
API documentation should be generated by gtk-doc, which collects specially formatted documentation comments from C and header files, and reformats them to generate DocBook and HTML output. The DocBook output can be used by Devhelp.
Using gtk-doc requires two things:
- The gtk-doc build system code to be integrated, which is a one-time operation.
- Documentation comments to be added to all public APIs, and kept up to date.
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.
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.)
If the package version is needed to be substituted into the documentation,
create a file named
Add it to
configure.ac, then include it into the main
documentation file (
DOCTYPE at the top of the document. The package version can then be
used inline as
Using a standard layout for the table of contents, sections, appendices, etc.
means the same
*-docs.xml template can be reused with few changes between
projects. It also means the documentation layout is similar across all
projects, making it more familiar to developers.
The following layout is suggested:
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. Generate the documentation using the rules described in
the D-Bus services guidelines.
The DocBook files can be included in the main
*-docs.xml file using:
The generated XML files must be included in the
content_files variable in
docs/reference/Makefile.am, otherwise the build will fail. (This is to fix
situations where the
builddir does not equal the
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.
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:
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
post-release version incrementing
is being used.
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:
Keeping documentation up to date
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, amongst other things.
These tests should always be enabled, by adding the following to
They will then be run as part of