Страницы QA

qdoc может генерировать дополнительные HTML-страницы, полезные для отладки документации qdoc. Эти страницы QA облегчают поиск ссылок, которые ведут не туда или вообще никуда, авторам документации.

Генерация страниц QA

Добавьте -write-qa-pages в командную строку, чтобы qdoc сгенерировал страницы QA. Если этот параметр не указан, страницы QA не будут сгенерированы, и ранее сгенерированные страницы QA будут удалены.

Поиск основной страницы QA модуля

Основная страница QA для модуля не ссылается на сгенерированную документацию модуля, но находится в том же выходном каталоге. Чтобы найти главную страницу QA для модуля xxx, откройте в браузере выходной каталог qdoc для модуля xxx. В списке наверху появятся несколько файлов, имена которых начинаются с aaa. Это страницы QA для модуля xxx. Имена файлов начинаются с aaa для удобства поиска в верхней части каталога.

Для модуля xxx найдите файл aaa-xxx-qa-page.html. Это главная страница QA для модуля xxx. Загрузите этот файл в браузер. Главная страница QA отображает таблицу, содержащую ссылки на несколько дополнительных страниц QA.

Например, основная страница QA для QtCore находится по адресу aaa-qtcore-qa-page.html. Раньше эта таблица для QtCore выглядела так:

Каждая строка таблицы показывает количество ссылок из QtCore на другой модуль, за исключением последней строки, которая показывает количество неработающих ссылок в QtCore. Нажмите на запись qtquick, чтобы загрузить страницу QA, показывающую ссылки из QtCore в QtQuick.

Страница ссылок на ссылки

Нажатие на запись qtquick в основной странице QA для QtCore загружает страницу QA, показывающую таблицу, содержащую все ссылки из QtCore в QtQuick. Таблица содержит все ссылки, созданные с помощью команды \l, а также автоматические ссылки.

На момент генерации этой таблицы было шесть ссылок из QtCore в QtQuick. Первый столбец каждой записи таблицы содержит ссылку на какую-то ссылку в QtCore. Текст ссылки, как он отображается в QtCore, показан. Второй и третий столбцы содержат имя файла и номер строки, где qdoc обнаружил ссылку в комментарии qdoc.

Примечание: Номер строки обычно относится к первой строке комментария, где qdoc обнаружил ссылку.

Нажатие на ссылку в таблице переводит вас к этой ссылке в документации. Там ссылка будет помечена тремя красными звёздочками. Например, нажатие на ссылку в пятой записи таблицы переводит вас сюда:

Ссылка помечена тремя красными звёздочками. Теперь вы можете нажать на фактическую ссылку, чтобы проверить, что она ведёт в нужное место. В данном случае ссылка должна перенаправлять на страницу справки класса QQuickItem. Вы можете проверить каждую ссылку в таблице таким образом. Если вы найдёте ссылку, ведущую не туда, используйте имя файла и номер строки, чтобы найти ссылку, и исправьте проблему, используя квадратные скобки для команды \l.