Введение в QDoc

QDoc — это инструмент, используемый разработчиками Qt для создания документации для проектов программного обеспечения. Он работает, извлекая комментарии QDoc из исходных файлов проекта, а затем форматирует эти комментарии в виде HTML-страниц или документов DITA XML. QDoc находит комментарии QDoc в .cpp файлах и в .qdoc файлах. QDoc не ищет комментарии QDoc в .h файлах. Комментарий QDoc всегда начинается со знака восклицания (!)). Например:

    / *!
        \class QObject
        \brief The QObject class is the base class of all Qt objects.

        \ingroup objectmodel

        \reentrant

        QObject is the heart of the Qt \l{Object Model}. The
        central feature in this model is a very powerful mechanism
        for seamless object communication called \l{signals and
        slots}. You can connect a signal to a slot with connect()
        and destroy the connection with disconnect(). To avoid
        never ending notification loops you can temporarily block
        signals with blockSignals(). The protected functions
        connectNotify() and disconnectNotify() make it possible to
        track connections.

        QObjects organize themselves in \l {Object Trees &
        Ownership} {object trees}. When you create a QObject with
        another object as parent, the object will automatically
        add itself to the parent's \c children() list. The parent
        takes ownership of the object. It will automatically
        delete its children in its destructor. You can look for an
        object by name and optionally type using findChild() or
        findChildren().

        Every object has an objectName() and its class name can be
        found via the corresponding metaObject() (see
        QMetaObject::className()). You can determine whether the
        object's class inherits another class in the QObject
        inheritance hierarchy by using the \c inherits() function.

    ....
* /

Из приведенного выше комментария QDoc генерируется страница справки класса QObject.

В данном руководстве объясняется, как использовать команды QDoc в комментариях QDoc, чтобы встраивать хорошую документацию в ваши исходные файлы. Также здесь объясняется, как создать файл конфигурации QDoc, который вы передадите QDoc в командной строке.

Выполнение QDoc

Имя программы QDoc — qdoc. Чтобы запустить QDoc из командной строки, передайте ему имя файла конфигурации:

$ ../../bin/qdoc ./config.qdocconf

QDoc распознает суффикс .qdocconf как файл конфигурации QDoc. В файле конфигурации вы указываете QDoc, где найти исходные файлы проекта, заголовочные файлы и .qdoc файлы. Здесь также указывается, какой тип вывода необходимо сгенерировать (HTML, DITA XML,...), и куда поместить сгенерированную документацию. Файл конфигурации также содержит другую информацию для QDoc.

Инструкции по настройке файла конфигурации QDoc см. в разделе Файл конфигурации QDoc.

Запуск QDoc в режиме одиночного выполнения

Начиная с Qt 5.5, доступен новый способ запуска QDoc, который сокращает время генерации документации Qt5 примерно на 90%. Новый способ запуска QDoc — режим одиночного выполнения. Режим одиночного выполнения в настоящее время недоступен в системе сборки Qt5, которая по-прежнему использует стандартный режим. Режим одиночного выполнения доступен только при самостоятельном запуске QDoc, что вам часто понадобится при документировании вашего модуля и интеграции вашей документации с другими модулями Qt.

Чтобы запустить QDoc в режиме одиночного выполнения, добавьте -single-exec в командную строку и передайте QDoc файл-мастер qdocconf , представляющий собой просто список путей к файлам qdocconf всех модулей Qt5. Например:

/Users/me/qt5/qtbase/bin/qdoc -outputdir /Users/me/qt5/qtbase/doc -installdir /Users/me/qt5/qtbase/doc /Users/me/qt5/master.qdocconf -single-exec

Файл qdocconf, master.qdocconf, просто перечисляет файлы qdocconf для всех модулей Qt5, которые необходимо обработать:

/Users/me/qt5/qtbase/src/corelib/doc/qtcore.qdocconf
/Users/me/qt5/qtbase/src/network/doc/qtnetwork.qdocconf
/Users/me/qt5/qtbase/src/sql/doc/qtsql.qdocconf
/Users/me/qt5/qtbase/src/xml/doc/qtxml.qdocconf
/Users/me/qt5/qtbase/src/testlib/doc/qttestlib.qdocconf
/Users/me/qt5/qtbase/src/concurrent/doc/qtconcurrent.qdocconf
/Users/me/qt5/qtbase/src/gui/doc/qtgui.qdocconf
/Users/me/qt5/qtbase/src/platformheaders/doc/qtplatformheaders.qdocconf
/Users/me/qt5/qtbase/src/widgets/doc/qtwidgets.qdocconf
/Users/me/qt5/qtbase/src/opengl/doc/qtopengl.qdocconf
/Users/me/qt5/qtbase/src/printsupport/doc/qtprintsupport.qdocconf
/Users/me/qt5/qtbase/src/tools/qdoc/doc/config/qdoc.qdocconf
/Users/me/qt5/qtbase/qmake/doc/qmake.qdocconf
/Users/me/qt5/qtsvg/src/svg/doc/qtsvg.qdocconf
/Users/me/qt5/qtxmlpatterns/src/xmlpatterns/doc/qtxmlpatterns.qdocconf
/Users/me/qt5/qtdeclarative/src/qml/doc/qtqml.qdocconf
/Users/me/qt5/qtdeclarative/src/quick/doc/qtquick.qdocconf
/Users/me/qt5/qtquickcontrols/src/controls/doc/qtquickcontrols.qdocconf
/Users/me/qt5/qtquickcontrols/src/layouts/doc/qtquicklayouts.qdocconf
/Users/me/qt5/qtquickcontrols/src/dialogs/doc/qtquickdialogs.qdocconf
/Users/me/qt5/qtmultimedia/src/multimedia/doc/qtmultimedia.qdocconf
/Users/me/qt5/qtmultimedia/src/multimediawidgets/doc/qtmultimediawidgets.qdocconf
/Users/me/qt5/qtactiveqt/src/activeqt/doc/activeqt.qdocconf
/Users/me/qt5/qtsensors/src/sensors/doc/qtsensors.qdocconf
/Users/me/qt5/qtwebkit/Source/qtwebkit.qdocconf
/Users/me/qt5/qttools/src/assistant/help/doc/qthelp.qdocconf
/Users/me/qt5/qttools/src/assistant/assistant/doc/qtassistant.qdocconf
/Users/me/qt5/qttools/src/designer/src/uitools/doc/qtuitools.qdocconf
/Users/me/qt5/qttools/src/designer/src/designer/doc/qtdesigner.qdocconf
/Users/me/qt5/qttools/src/linguist/linguist/doc/qtlinguist.qdocconf
/Users/me/qt5/qtwebkit-examples/doc/qtwebkitexamples.qdocconf
/Users/me/qt5/qtgraphicaleffects/src/effects/doc/qtgraphicaleffects.qdocconf
/Users/me/qt5/qtscript/src/script/doc/qtscript.qdocconf
/Users/me/qt5/qtscript/src/scripttools/doc/qtscripttools.qdocconf
/Users/me/qt5/qtserialport/src/serialport/doc/qtserialport.qdocconf
/Users/me/qt5/qtdoc/doc/config/qtdoc.qdocconf

Почему стандартный режим медленный

В настоящее время система сборки Qt5 не использует режим одиночного выполнения QDoc для генерации документации Qt5. Она запускает QDoc в стандартном режиме. Стандартный режим возник потому, что это был самый простой способ заставить Qt4 QDoc обрабатывать модульность Qt в Qt5. В Qt4 QDoc выполнялся один раз над всеми исходными кодами Qt4 для генерации HTML-документации Qt. Во время генерации документации Qt4 QDoc также генерировал индексный файл для Qt. Этот индексный файл предназначался для использования в последующих запусках QDoc для генерации HTML-документации для других библиотек/продуктов, основанных на Qt. Индексный файл Qt позволял QDoc связывать документацию, написанную для этих других библиотек/продуктов, с документацией Qt4.

Когда появился Qt5, Qt был разделен на модули. С тех пор к Qt было добавлено много новых модулей. По состоянию на версию 5.5 в Qt5 более 40 отдельных модулей, каждый со своей документацией, которая ссылается (зависит) от документации других модулей Qt.

В стандартном режиме QDoc выполняется дважды для каждого модуля. Первый запуск QDoc для конкретного модуля Qt анализирует все исходные файлы модуля, а затем использует эту информацию для генерации индексного файла модуля. Это называется фазой подготовки, потому что он подготавливает индексный файл модуля. Второй запуск QDoc для модуля также анализирует все исходные файлы модуля, а затем генерирует страницы документации модуля. Это называется фазой генерации, потому что она генерирует документацию модуля.

Документация модуля, вероятно, будет содержать HTML-ссылки на документацию одного или нескольких других модулей Qt. Например, большинство модулей Qt5 содержат ссылки на документацию в QtCore. Когда модуль Qt содержит ссылки в документацию другого модуля Qt, говорится, что этот модуль зависит от этих других модулей Qt. Следовательно, когда QDoc выполняет фазу генерации для этого модуля, он также должен загрузить индексные файлы этих модулей, чтобы он мог создать эти ссылки.

Поэтому, когда система сборки Qt генерирует документацию Qt, она сначала запускает QDoc один раз для каждого модуля, чтобы выполнить фазу подготовки для генерации всех индексных файлов. Затем она запускает QDoc один раз для каждого модуля, чтобы выполнить фазу генерации, где она использует зависимые индексные файлы для генерации документации модуля, включая любые межмодульные ссылки, которые она находит. Каждое выполнение QDoc, как фаза подготовки, так и фаза генерации, анализирует все исходные файлы, включенные в модуль, а в фазе генерации также анализирует индексные файлы зависимых модулей. Ничто не сохраняется и не может быть сохранено между запусками QDoc.

Почему режим одиночного выполнения намного быстрее

Как следует из названия, режим одиночного выполнения использует один процесс QDoc для генерации всей документации Qt5. Единственный процесс QDoc по-прежнему выполняет фазу подготовки для каждого модуля, а затем фазу генерации для каждого модуля, но есть несколько различий. Он начинает с чтения файла qdocconf-мастера. Затем он считывает каждый файл qdocconf в главном списке и выполняет фазу подготовки для каждого модуля. Во время фазы подготовки все исходные файлы модуля анализируются для построения синтаксического дерева модуля. Индексный файл модуля генерируется, хотя QDoc не будет повторно читать индексные файлы в фазе генерации. Важное различие заключается в том, что синтаксическое дерево модуля сохраняется после генерации индексного файла, так что после выполнения фазы подготовки для всех модулей QDoc по-прежнему имеет все построенные им синтаксические деревья.

Затем QDoc снова обрабатывает каждый модуль для фазы генерации. Но теперь QDoc не нужно повторно анализировать исходные файлы каждого модуля, потому что синтаксическое дерево модуля все еще находится в памяти. QDoc также не нужно повторно читать индексные файлы зависимых модулей, опять же, потому что он все еще имеет синтаксические деревья этих модулей в памяти. Осталось только пройти по синтаксическому дереву каждого модуля, чтобы сгенерировать страницы документации.

Таким образом, QDoc анализирует каждый исходный файл один раз и только один раз и не нуждается в чтении индексных файлов. Именно это делает режим одиночного выполнения намного быстрее, чем стандартный режим. Ожидается, что система сборки Qt в конечном итоге запустит QDoc в режиме одиночного выполнения. Однако могут потребоваться изменения в файле qdocconf-мастера, поэтому описанный выше метод запуска QDoc в режиме одиночного выполнения может потребовать изменения, следите за обновлениями.

Как работает QDoc

QDoc начинает с чтения файла конфигурации, указанного вами в командной строке. Он сохраняет все переменные из файла конфигурации для последующего использования. Одна из первых переменных, которую он использует, — outputformats. Эта переменная сообщает QDoc, какие генераторы вывода будут запущены. Значение по умолчанию — HTML, поэтому, если вы не установите outputformats в файле конфигурации, QDoc сгенерирует вывод HTML. Обычно это то, чего вы хотите, но вы также можете указать DITAXML, чтобы получить вывод DITA XML вместо этого.

Далее QDoc использует значения переменной headerdirs и/или переменной headers для поиска и анализа всех заголовочных файлов вашего проекта. QDoc не сканирует заголовочные файлы на предмет комментариев QDoc. Он анализирует заголовочные файлы, чтобы построить главное дерево всех элементов, которые должны быть задокументированы, другими словами, элементов, для которых QDoc должен найти комментарии QDoc.

После анализа всех заголовочных файлов и построения главного дерева элементов, подлежащих документированию, QDoc использует значение переменной sourcedirs и/или значение переменной sources для поиска и анализа всех .cpp и .qdoc файлов вашего проекта. Это файлы, которые QDoc сканирует на предмет комментариев QDoc. Помните, что комментарий QDoc начинается с восклицательного знака: /*! .

Для каждого найденного комментария QDoc он ищет в главном дереве элемент, где находится документация. Затем он интерпретирует команды QDoc в комментарии и сохраняет интерпретированные команды и текст комментария в узле дерева для элемента.

Наконец, QDoc проходит по главному дереву. Для каждого узла, если у узла есть сохраненная документация, QDoc вызывает генератор вывода, указанный переменной outputformats, чтобы отформатировать и записать документацию в каталог, указанный в файле конфигурации в переменной outputdir.

Типы команд

QDoc интерпретирует три типа команд:

• Команды тем
• Команды контекста
• Команды разметки

Команды тем идентифицируют элемент, который вы документируете, например, класс C++, функцию, тип или дополнительную страницу текста, которая не соответствует базовому элементу C++.

Команды контекста сообщают QDoc, как элемент, подлежащий документированию, связан с другими задокументированными элементами, например, следующими и предыдущими страницами, включением в группы страниц или модули библиотек. Команды контекста также могут предоставлять информацию об элементах, которые QDoc не может получить из исходных файлов, например, о том, является ли элемент потокобезопасным, является ли он перегруженной или переопределённой функцией, или устаревшим.

Команды разметки сообщают QDoc, как должны отображаться элементы текста и изображений в документе, или о структуре оглавления документа.