Documentation

The preferred documentation system for GNOME libraries is gtk-doc, which extracts inline comments from the code to let you build a DocBook document and collection of HTML pages. These can then be read in Devhelp. A lot of GNOME’s infrastructure is built to handle with documentation written using gtk-doc.

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

If the package version is needed to be substituted into the documentation, create a file named docs/version.xml.in, containing:

@PACKAGE_VERSION@

Add it to AC_CONFIG_FILES in configure.ac, then include it into the main documentation file (*-docs.xml) using: <!ENTITY version SYSTEM "version.xml"> in the DOCTYPE at the top of the document. The package version can then be used inline as &version;.

Using a standard layout for the table of contents, sections, appendices, etc. means the same project-name-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:

<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
  <!ENTITY version SYSTEM "version.xml">
]>
<book id="index">
  <bookinfo>
    <title>[project] Reference Manual</title>
    <releaseinfo>
      For [project] &version;. The latest version of this documentation can be found on-line at
      <ulink role="online-location" url="http://[server]/[project]/index.html">http://[server]/[project]/</ulink>.
    </releaseinfo>
  </bookinfo>

  <part>
    <title>[project] Overview</title>

    <xi:include href="xml/SomeObject.xml"/>
    <xi:include href="xml/OtherObject.xml"/>
    <xi:include href="xml/Utilities.xml"/>

    <chapter>
      <title>Object Hierarchy</title>
      <xi:include href="xml/tree_index.sgml"/>
    </chapter>
  </part>

  <part>
    <title>D-Bus Interfaces</title>

    <chapter>
      <title>D-Bus Interfaces</title>

      <partintro>
        <para>D-Bus interface definitions for the project.</para>
      </partintro>

      <xi:include href="xml/docs-Some.Interface.xml"/>
      <xi:include href="xml/docs-Other.Interface.xml"/>
    </chapter>

    <chapter>
      <title>C Interfaces</title>

      <partintro>
        <para>C wrappers for the project D-Bus interfaces.</para>
      </partintro>

      <xi:include href="xml/SomeInterface.xml"/>
      <xi:include href="xml/OtherInterface.xml"/>
    </chapter>
  </part>

  <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="1.0.0">
      <title>Index of new symbols in 1.0.0</title>
      <xi:include href="xml/api-index-1.0.0.xml"><xi:fallback/></xi:include>
    </index>
    <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
  </part>

  <xi:include href="xml/license.xml"/>
  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</book>

It is important to make the license used for API references clear, especially if they contain code examples which could be copied around.

Typically, projects use the same license for their API reference as for the project’s code itself, to avoid confusion. Some other projects use CC-BY-SA 3.0 for all their reference documentation. The choice is yours.

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.

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

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

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 configure.ac if post-release version incrementing is being used.

For example:

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

The DocBook files can be included in the main *-docs.xml file using:

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

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.

These tests should always be enabled, by adding the following to your gtk-doc Makefile.am:

TESTS = $(GTKDOC_CHECK)

They will then be run as part of make check.