Страницы 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.