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