QA Pages

qdoc can generate some extra HTML pages that can be useful for debugging qdoc documentation. These QA pages make it easier for those who write documentation to find links that either go to the wrong targets or don't go anywhere at all.

Generating the QA Pages

Add -write-qa-pages to the command line to tell qdoc to generate the QA pages. If this option is not provided, the QA pages will not be generated, and previolusly generated QA pages will be deleted.

Finding the Module's Main QA Page

The main QA page for a module is not linked into the module's generated documentation, but it is located in the same output directory. To find the top-level QA page for module xxx, set your browser to the qdoc output directory for module xxx. Several files whose names begin with aaa appear at the top of the list. These are the QA pages for module xxx. The file names begin with aaa to ensure that they are easy to find at the top of the directory.

For module xxx, find the file aaa-xxx-qa-page.html. This is the top-level QA page for module xxx. Load that file into the browser. The top-level QA page shows a table that contains links to several QA sub-pages.

For example, the main QA page for QtCore is aaa-qtcore-qa-page.html. This was the table for QtCore at one point:

Each table entry shows the number of links from QtCore to some other module, except for the last entry, which shows the number of broken links in QtCore. Click the qtquick entry to load the QA subpage showing the links from QtCore to QtQuick.

Links To Links Page

Clicking the qtquick table entry on the main QA page for QtCore loads the QA subpage showing a table containing all the links from QtCore to QtQuick. The table contains all the links constructed with the \l command, as well as the autolinks.

At the time this table was generated, there were six links from QtCore to QtQuick. The first column of each table entry contains a link to some link in QtCore. The link text as it appears in QtCore is shown. The second and third columns contain the source file name and line number for where qdoc saw the link in a qdoc comment.

Note: The line number will normally refer to the first line of the comment where qdoc saw the link.

Clicking on a link in the table takes you to that link in the documentation. There the link will be marked with three red asterisks. For example, clicking on the link in the fifth table entry takes you here:

The link is marked with three red asterisks. Now you can click on the actual link to check that it goes to the correct place. In this case, the link should go to the reference page for the QQuickItem class. You can check each link in the table this way. If you find a link that goes to the wrong place, use the source file name and line number to find the link, and fix the problem using the square bracket notation for the \l command.