Troubleshooting Qt Documentation

h1. Troubleshooting Qt Documentation

When Writing Qt Documentation and Building Qt Documentation, sometimes the classes, QML elements, or manual pages you have written fail to appear in the documentation generated by qdoc. This is usually caused by a misconfigured or incomplete project file (for example, qt-project.qdocconf) or errors in the documentation comments themselves. Most people encountering these problems are frustrated by the lack of diagnostic output from qdoc, but in many cases qdoc cannot complain about documentation it is not aware of.

Fortunately, there are a number of steps you can take to diagnose the particular problem you are encountering. It may be caused by one or more of the following issues.

Source and/or header paths not included in the qdocconf file for the project

The configuration file should contain sourcedirs, headerdirs, sources and headers declarations to tell qdoc where to look for source and header files. Typically, sourcedirs and headerdirs are used because they specify directories that contain those types of files rather than specific files; in addition, qdoc searches those directories recursively.

Make sure that the directory containing your header files is included in the headerdirs list, or that the paths to the header files are specified in the headers list. Also make sure that the source directories are included in the sourcedirs list, or that the paths to the source files are specified in the sources list. Check to make sure that you have spelt these declarations correctly.

Source and/or header paths are excluded from the search paths

The excludedirs declaration is used to remove directories from the sourcedirs and headerdirs lists. Historically, the addition of this declaration made it possible to speed up Qt documentation generation by removing all the third party source directories from the list of directories scanned by qdoc.

Problems can occur if the list of excluded directories is too broad and your sources and headers are excluded. Consider narrowing the list of excluded directories to avoid excluding too much.

File extension not included in the list in the qdocconf file

Traditionally, the range of file extensions supported by qdoc is restricted to those associated with C++ and qdoc itself. If you have inherited a qdocconf file from an old project, it will not include extensions like *.qml in the sources.fileextensions and headers.fileextensions declarations. Indeed, if these declarations are not present in the configuration file, qdoc will use a default list that only includes C+-related file extensions, so it is often preferable to provide your own list.
Similarly, if you have written an example and its files are not recognized correctly, the examples.fileextensions and examples.imageextensions declarations may need to be expanded to include the range of file extensions required for your example.
h3. Classes with unknown tokens or macros
Qt uses various preprocessor macros to indicate that the symbols for certain classes should be exported by the Qt libraries. qdoc needs to be informed about these, and the Qt documentation contains a configuration file called qt-cpp-ignore.qdocconf that allows these to be listed. The Cpp.ignoretokens declaration contains a list of zero-argument macros that qdoc needs to ignore. The Cpp.ignoredirectives declaration contains a similar list of macros that accept arguments.
h3. Undefined macros cause documentation to be excluded
Because the same Qt source code is designed to be compiled on multiple platforms, the preprocessor is used to test which platform is being used when the compiler is running. qdoc performs simple tests on preprocessor symbols to ensure that as much C+ can be read as possible. The Qt documentation contains the qt-defines.qdocconf file which is used to define the symbols that it should recognize when parsing the source and header files. Since the Qt documentation has traditionally been built to include documentation for all platforms, symbols such as Q_WS_X11 and Q_OS_WIN are defined.

If you are using preprocessor tests in your code, ensure that you have defined the symbols used in your qdocconf file. Additionally, try and keep comments with functions instead of being separated from them by preprocessor tests.

Documentation in header files

Unlike Doxygen, qdoc does not look for comments in header files. If you can, move them into source files or create new .qdoc files to contain the documentation comments.

Unrecognized comments: either plain C-style comments or Doxygen-style comment
qdoc recognizes comments that begin with /*! as documentation. Other comment styles are not recognized.

Lack of a , , or other qdoc command in the comment
To register function documentation, it is enough to include a documentation comment before the function implementation in the source code. However, since the documentation for classes is written in a different file to the class declaration, the documentation comment for a class requires a command as a declaration.

Similarly, QML elements implemented in C++ are defined in a C++ header file, so their documentation requires a to be used for each QML element.

Pages are pure documentation that are not associated with source code. As a result, their documentation comments require a declaration and usually a eclaration.

QML element defined using a in one file with commands in another
Unlike C++ classes which have a declaration in a header file and an implementation in one or more source files, QML elements are not defined in the same way. C++ classes can have documentation spread across multiple files, with one declaration separated from , and other declarations. QML elements are limited to having all documentation in one file.