Qt Weekly is back from vacation with a post from a guest blogger (*applause*).  In this post, Lorenz Haas tells us how to link Qt classes in custom documentation that is generated by using Doxygen.

By mid-2008, Sebastian Pipping introduced doxygen2qthelp for generating Qt Compressed Help files (*.qch) via Doxygen. Already by the end of the year, it was successfully merged into Doxygen. While 1.5.7.1 still had some mirror problems, version 1.5.8 provided stable and comprehensive support for creating QCH files out of the box. See Sebastian's announcement as well as David Boddie's article in Qt Quarterly.

Since then, this feature – I guess – has been used a thousand, a million times. Nowadays, I personally can't imagine working without it. This is because it integrates perfectly into my favorite IDE – Qt Creator. There I can use my own documentation for context-sensitive help that can be triggered by the F1-shortcut:

However, one tiny, but very annoying detail spoils the party. Qt classes don't get linked and so you can't conveniently click on a piece of text, such as QString, to open the documentation of QString. In Qt's own help files that come with Qt Creator, however, you can click every Qt class and you are thus used to doing so. So let's see how we can rock the party with custom help files.

Before we do so, however, let's briefly summarize how we generate the custom help file that is shown in the picture.

Generating Help Files

First, we have a small example file – main.cpp – posing as the full documented project:

class SomeClass {
public:
  /**
   * \brief A simple description
   *
   * Here is the documentation body containing references
   * to Qt functions like QPixmap::copy().
   */
  QString getText(const QDomElement &e);
};

Second, we create a basic configuration file for Doxygen by calling:

doxygen -g doxyfile.cfg

We edit the following options:

INPUT                  = main.cpp
GENERATE_QHP           = YES
QCH_FILE               = ../MyDoc.qch
QHP_NAMESPACE          = your.domain.project
QHG_LOCATION           = /path/to/qhelpgenerator

You'll find detailed documentation for these options – as well as for all the other options – in the generated configuration file.

Third, we actually need to call Doxygen with this configuration file:

doxygen doxyfile.cfg

Finally, we have to open Qt Creator, select Tools > Options > Help > Documentation and add the generated  Qt Compressed Help file there. That's all.

Creating Links

So, how do we get the links? As a matter of fact, we need to tell Doxygen where it can find information about the Qt classes. This information is stored in so called tag files that Doxygen generates if you specify GENERATE_TAGFILE.

Although Qt Project uses QDoc to generate the documentation, it also generates tag files we can use with Doxygen. They are located in the directory Docs/Qt-5.3 where you have installed Qt. The tag file for each module is then located in the respective subfolder. E.g. the tag file for QtCore is located at Docs/Qt-5.3/qtcore/qtcore.tags. For convenience, we copy all the needed tag files for the modules we reference beside the Doxygen configuration file.

Now, we use TAGFILES to make the tag files usable for Doxygen. The syntax of  TAGFILES entries is as follows:

<path to the tag file>=<path>

The path should be prepended to the (relative) link specified by the tag file.

If you like to use the documentation inside Qt Creator and use the local help files of Qt, the prepend path for QtCore looks like this:

qthelp://org.qt-project.qtcore/qtcore/

The URL schema qthelp:// will cause Qt Creator's help engine to use the local available documentation, org.qt-project.qtcore corresponds to QHP_NAMESPACE, and qtcore to QHP_VIRTUAL_FOLDER. So, TAGFILES for our example looks like this:

TAGFILES = qtcore.tags=qthelp://org.qt-project.qtcore/qtcore/ \
           qtgui.tags=qthelp://org.qt-project.qtgui/qtgui/ \
           qtxml.tags=qthelp://org.qt-project.qtxml/qtxml/

If we now recreate the documentation and open it, we'll see that QString, QDomDocument, and
QPixmap::copy() link to the Qt documentation. And even Qt links to the Qt
namespace documentation!

Last, two little hints:

• If you'd like to link to a specific version of Qt documentation, you can define that after the namespace. So qthelp://org.qt-project.qtcore.531/qtcore/ would generate links that point to the QtCore documentation for Qt 5.3.1.
• If you create online documentation, use e.g. qtcore.tags=http://qt-project.org/doc/qt-5/ to create links pointing to the official online documentation of Qt. As for the URL, you do not have to specify the module.

So go on, pimp your docs and happy documenting :)

By Lorenz Haas