GTK-Doc Manual

GTK-Doc is used to document C code. It is typically used to document the public API of libraries, such as the GTK+ and GNOME libraries, but it can also be used to document application code.

GTK-Doc works by using documentation of functions placed inside the source files in specially-formatted comment blocks, or documentation added to the template files which GTK-Doc uses (though note that GTK-Doc will only document functions that are declared in header files; it won't produce output for static functions).

GTK-Doc consists of a number of Perl scripts, each performing a different step in the process.

There are 5 main steps in the process:

(FIXME)

(History, authors, web pages, licence, future plans, comparison with other similar systems.)

(FIXME)

(who it is meant for, where you can get it, licence)

Under your top-level project directory create a folder called docs/reference (this way you can also have docs/help for end-user documentation). It is recommended to create another subdirectory with the name of the doc-package. For packages with just one library this step is not necessary.

This can then look as shown below:

meep/
  docs/
    reference/
      libmeep/
      meeper/
  src/
    libmeep/
    meeper/

          

Very easy! Just add one line to your configure.ac script.

# check for gtk-doc
GTK_DOC_CHECK([1.14],[--flavour no-tmpl])

          

This will require all developers to have gtk-doc installed. If it is okay for your project to have optional api-doc build setup, you can solve this as below. Keep it as is, as gtkdocize is looking for GTK_DOC_CHECK at the start of a line.

# check for gtk-doc
m4_ifdef([GTK_DOC_CHECK], [
GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
],[
AM_CONDITIONAL([ENABLE_GTK_DOC], false)
])

          

The first argument is used to check for the gtkdocversion at configure time. The 2nd, optional argument is used by gtkdocize. The GTK_DOC_CHECK macro also adds several configure switches:

Furthermore it is recommended that you have the following line inside you configure.ac script. This allows gtkdocize to automatically copy the macro definition for GTK_DOC_CHECK to your project.

AC_CONFIG_MACRO_DIR(m4)

          

First copy the Makefile.am from the examples sub directory of the gtkdoc-sources to your project's API documentation directory ( ./docs/reference/<package>). A local copy should be available under e.g. /usr/share/doc/gtk-doc-tools/examples/Makefile.am. If you have multiple doc-packages repeat this for each one.

The next step is to edit the settings inside the Makefile.am. All the settings have a comment above that describes their purpose. Most settings are extra flags passed to the respective tools. Every tool has a variable of the form <TOOLNAME>_OPTIONS. All the tools support --help to list the supported parameters.

Most projects will have an autogen.sh script to setup the build infrastructure after a checkout from version control system (such as cvs/svn/git). GTK-Doc comes with a tool called gtkdocize which can be used in such a script. It should be run before autoheader, automake or autoconf.

gtkdocize || exit 1

          

When running gtkdocize it copies gtk-doc.make to your project root (or any directory specified by the --docdir option). It also checks you configure script for the GTK_DOC_CHECK invocation. This macro can be used to pass extra parameters to gtkdocize.

Historically GTK-Doc was generating template files where developers entered the docs. This turned out to be not so good (e.g. the need for having generated files under version control). Since GTK-Doc 1.9 the tools can get all the information from source comments and thus the templates can be avoided. We encourage people to keep documentation in the code. gtkdocize supports now a --flavour no-tmpl option that chooses a makefile that skips tmpl usage totally. Besides adding the option directly to the command invocation, they can be added also to an environment variable called GTKDOCIZE_FLAGS or set as a 2nd parameter in GTK_DOC_CHECK macro in the configure script. If you have never changed file in tmpl by hand and migrating from older gtkdoc versions, please remove the directory (e.g. from version control system).

After the previous steps it is time to run the build. First we need to rerun autogen.sh. If this script runs configure for you, then give it the --enable-gtk-doc option. Otherwise manually run configure with this option afterwards.

The first make run generates several additional files in the doc-directories. The important ones are: <package>.types, <package>-docs.xml (in the past .sgml), <package>-sections.txt.

./autogen.sh --enable-gtk-doc
make

          

Now you can point your browser to docs/reference/package/index.html. Yes, it's a bit disappointing still. But hang on; during the next chapter we tell you how to fill the pages with life.

As a rule of the thumb, it's those files you edit, that should go under version control. For typical projects it's these files: <package>.types, <package>-docs.xml (in the past .sgml), <package>-sections.txt, Makefile.am

In the case one does not want to use automake and therefore gtk-doc.mak one will need to call the gtkdoc tools in the right order in own makefiles (or other build tools).

DOC_MODULE=meep
// sources have changed
gtkdoc-scan --module=$(DOC_MODULE) --source-dir=...
gtkdoc-scangobj --module=$(DOC_MODULE)
gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml
// xml files have changed
mkdir html
cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml
gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html

          

One will need to look at the Makefile.am and gtk-doc.mak to pick the extra options needed.

A multiline comment that starts with an additional '*' marks a documentation block that will be processed by the GTK-Doc tools.

/**
 * identifier:
 * documentation ...
 */

          

The 'identifier' is one line with the name of the item to which the comment is related. The syntax differs a little depending on the item. (TODO add table showing identifiers)

The 'documentation' block is also different for each symbol type. Symbol types that get parameters such as functions or macros have the parameter description first followed by a blank line (just a '*'). Afterwards follows the detailed description. All lines (outside program listings and CDATA sections) just containing a ' *' (blank-asterisk) are converted to paragraph breaks. If you don't want a paragraph break, change that into ' * ' (blank-asterisk-blank-blank). This is useful in preformatted text (code listings).

One advantage of hyper-text over plain-text is the ability to have links in the document. Writing the correct markup for a link can be tedious though. GTK-Doc comes to help by providing several useful abbreviations.

DocBook can do more than just links. One can also have lists, examples, headings, and images. As of version 1.20, the preferred way is to use a subset of the basic text formatting syntax called Markdown. On older GTK-Doc versions any documentation that includes Markdown will be rendered as is. For example, list items will appear as lines starting with a dash.

In older GTK-Doc releases, if you need support for additional formatting, you would need to enable the usage of docbook SGML/XML tags inside doc-comments by putting --xml-mode or --sgml-mode in the variable MKDB_OPTIONS inside Makefile.am.

/**
 * identifier:
 *
 * documentation paragraph ...
 *
 * # Sub Heading #
 *
 * ## Second Sub Heading
 *
 * # Sub Heading With a Link Anchor # {#heading-two}
 *
 * more documentation:
 *
 * - list item 1
 *
 *   Paragraph inside a list item.
 *
 * - list item 2
 *
 * 1. numbered list item
 *
 * 2. another numbered list item
 *
 * Another paragraph. [A Link to the GNOME Website](http://www.gnome.org/)
 *
 * ![an inline image][plot-result.png]
 *
 * [A link to the heading anchor above][heading-two]
 *
 * A C-language example:
 * |[<!-- language="C" -->
 * GtkWidget *label = gtk_label_new ("Gorgeous!");
 * ]|
 */

          

More examples of what markdown tags are supported can be found in the GTK+ Documentation Markdown Syntax Reference.

Each section of the documentation contains information about one class or module. To introduce the component one can write a section block. The short description is also used inside the table of contents. All the @fields are optional.

/**
 * SECTION:meepapp
 * @short_description: the application class
 * @title: Meep application
 * @section_id:
 * @see_also: #MeepSettings
 * @stability: Stable
 * @include: meep/app.h
 * @image: application.png
 *
 * The application class handles ...
 */

          

Each symbol (function, macro, struct, enum, signal and property) is documented in a separate block. The block is best placed close to the definition of the symbols so that it is easy to keep them in sync. Thus functions are usually documented in the c-source and macros, structs and enums in the header file.

/**
 * foo_get_bar:
 * @foo: some foo
 *
 * Retrieves @foo's bar.
 *
 * Returns: @foo's bar
 *
 * Since: 2.6
 * Deprecated: 2.12: Use foo_baz_get_bar() instead.
 */
Bar *
foo_get_bar(Foo *foo)
{
...

          

/**
 * function_name:
 * @par1:  description of parameter 1. These can extend over more than
 * one line.
 * @par2:  description of parameter 2
 * @...: a %NULL-terminated list of bars
 *
 * The function description goes here. You can use @par1 to refer to parameters
 * so that they are highlighted in the output. You can also use %constant
 * for constants, function_name2() for functions and #GtkWidget for links to
 * other declarations (which may be documented elsewhere).
 *
 * Returns: an integer.
 *
 * Since: 2.2
 * Deprecated: 2.18: Use other_function() instead.
 */

          

/**
 * SomeWidget:some-property:
 *
 * Here you can document a property.
 */
g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);

          

/**
 * FooWidget::foobarized:
 * @widget: the widget that received the signal
 * @foo: some foo
 * @bar: some bar
 *
 * The ::foobarized signal is emitted each time someone tries to foobarize @widget.
 */
foo_signals[FOOBARIZE] =
  g_signal_new ("foobarize",
                ...

          

/**
 * FooWidget:
 * @bar: some #gboolean
 *
 * This is the best widget, ever.
 */
typedef struct _FooWidget {
  /*< private >*/
  GtkWidget parent;

  /*< public >*/
  gboolean bar;
} FooWidget;

          

/**
 * Something:
 * @SOMETHING_FOO: something foo
 * @SOMETHING_BAR: something bar
 *
 * Enum values used for the thing, to specify the thing.
 */
typedef enum {
  SOMETHING_FOO,
  SOMETHING_BAR,
  /*< private >*/
  SOMETHING_COUNT
} Something;

          

Here are some DocBook tags which are most useful when documenting the code.

To link to another section in the GTK docs:

<link linkend="glib-Hash-Tables">Hash Tables</link>

          

To refer to an external function, e.g. a standard C function:

<function>...</function>

          

To include example code:

<example>
  <title>Using a GHashTable.</title>
  <programlisting>
      ...
  </programlisting>
</example>

          

<informalexample>
  <programlisting>
  ...
  </programlisting>
</informalexample>

          

To include bulleted lists:

<itemizedlist>
  <listitem>
    <para>
      ...
    </para>
  </listitem>
  <listitem>
    <para>
      ...
    </para>
  </listitem>
</itemizedlist>

          

To include a note which stands out from the text:

<note>
  <para>
    Make sure you free the data after use.
  </para>
</note>

          

To refer to a type:

<type>unsigned char</type>

          

To refer to an external structure (not one described in the GTK docs):

<structname>XFontStruct</structname>

          

To refer to a field of a structure:

<structfield>len</structfield>

          

To refer to a class name, we could possibly use:

<classname>GtkWidget</classname>

          

To emphasize text:

<emphasis>This is important</emphasis>

          

For filenames use:

<filename>/home/user/documents</filename>

          

To refer to keys use:

<keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>

          

If your library or application includes GObjects, you want their signals, arguments/parameters and position in the hierarchy to be shown in the documentation. All you need to do, is to list the xxx_get_type functions together with their include inside the <package>.types file.

#include <gtk/gtk.h>

gtk_accel_label_get_type
gtk_adjustment_get_type
gtk_alignment_get_type
gtk_arrow_get_type

          

Since GTK-Doc 1.8 gtkdoc-scan can generate this list for you. Just add "--rebuild-types" to SCAN_OPTIONS in Makefile.am. If you use this approach you should not dist the types file nor have it under version control.

GTK-Doc produces documentation in DocBook SGML/XML. When processing the inline source comments, the GTK-Doc tools generate one documentation page per class or module as a separate file. The master document includes them and place them in an order.

While GTK-Doc creates a template master document for you, later run will not touch it again. This means that one can freely structure the documentation. That includes grouping pages and adding extra pages. GTK-Doc has now a test suite, where also the master-document is recreated from scratch. Its a good idea to look at this from time to time to see if there are some new goodies introduced there.

So what are the things to change inside the master document? There are some placeholders (text in square brackets) there which you should take care of.

<bookinfo>
  <title>MODULENAME Reference Manual</title>
  <releaseinfo>
    for MODULENAME [VERSION]
    The latest version of this documentation can be found on-line at
    <ulink role="online-location" url="http://[SERVER]/MODULENAME/index.html">http://[SERVER]/MODULENAME/</ulink>.
  </releaseinfo>
</bookinfo>

<chapter>
  <title>[Insert title here]</title>

          

The section file is used to organise the documentation output by GTK-Doc. Here one specifies which symbol belongs to which module or class and control the visibility (public or private).

The section file is a plain text file with XML-like syntax (using tags). Blank lines are ignored and lines starting with a '#' are treated as comment lines.

The <FILE> ... </FILE> tag is used to specify the file name, without any suffix. For example, using '<FILE>gnome-config</FILE>' will result in the section declarations being output in the template file tmpl/gnome-config.sgml, which will be converted into the DocBook SGML/XML file sgml/gnome-config.sgml or the DocBook XML file xml/gnome-config.xml. (The name of the HTML file is based on the module name and the section title, or for GObjects it is based on the GObjects class name converted to lower case).

The <TITLE> ... </TITLE> tag is used to specify the title of the section. It is only useful before the templates (if used) are initially created, since the title set in the template file overrides this. Also if one uses SECTION comment in the sources, this is obsolete.

You can group items in the section by using the <SUBSECTION> tag. Currently it outputs a blank line between subsections in the synopsis section. You can also use <SUBSECTION Standard> for standard GObject declarations (e.g. the functions like g_object_get_type and macros like G_OBJECT(), G_IS_OBJECT() etc.). Currently these are left out of the documentation. You can also use <SUBSECTION Private> for private declarations which will not be output (it is a handy way to avoid warning messages about unused declarations). If your library contains private types which you don't want to appear in the object hierarchy and the list of implemented or required interfaces, add them to a Private subsection. Whether you would place GObject and GObjectClass like structs in public or Standard section depends if they have public entries (variables, vmethods).

You can also use <INCLUDE> ... </INCLUDE> to specify the #include files which are shown in the synopsis sections. It contains a comma-separated list of #include files, without the angle brackets. If you set it outside of any sections, it acts for all sections until the end of the file. If you set it within a section, it only applies to that section.

When using xml instead of sgml, one can actually name the master document <package>-docs.xml.

This version supports SCAN_OPTIONS=--rebuild-sections in Makefile.am. When this is enabled, the <package>-sections.txt is autogenerated and can be removed from the vcs. This only works nicely for projects that have a very regular structure (e.g. each .{c,h} pair will create new section). If one organize a project close to that updating a manually maintained section file can be as simple as running meld <package>-decl-list.txt <package>-sections.txt.

Version 1.8 already introduced the syntax for documenting sections in the sources instead of the separate files under tmpl. This version adds options to switch the whole doc module to not use the extra tmpl build step at all, by using --flavour no-tmpl in configure.ac.

This version supports SCAN_OPTIONS=--rebuild-types in Makefile.am. When this is enabled, the <package>.types is autogenerated and can be removed from the vcs. When using this feature it is important to also setup the IGNORE_HFILES in Makefile.am for code that is build conditionally.

This version includes a new tool called gtkdoc-check. This tool can run a set of sanity checks on your documentation. It is enabled by adding these lines to the end of Makefile.am.

if ENABLE_GTK_DOC
TESTS_ENVIRONMENT = \
  DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
  SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
TESTS = $(GTKDOC_CHECK)
endif

          

Version 1.18 brought some initial markdown support. Using markdown in doc comments is less intrusive than writing docbook xml. This version improves a lot on this and add a lot more styles. The section that explains the comment syntax has all the details.

As one can generate man pages for a docbook refentry as well, it sounds like a good idea to use it for that purpose. This way the interface is part of the reference and one gets the man-page for free.

AC_ARG_ENABLE(man,
              [AC_HELP_STRING([--enable-man],
                              [regenerate man pages from Docbook [default=no]])],enable_man=yes,
              enable_man=no)

AC_PATH_PROG([XSLTPROC], [xsltproc])
AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)

            

man_MANS = \
       meeper.1

if ENABLE_GTK_DOC
if ENABLE_MAN

%.1 : %.xml
        @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<

endif
endif

BUILT_EXTRA_DIST = $(man_MANS)
EXTRA_DIST += meep.xml

            

(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)