Общие переменные конфигурации

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

alias

Переменная alias переименовывает команду QDoc.

Общая синтаксис alias.original-command-name = temporary-command-name.

alias.e = i

Это переименовывает встроенную команду \e (курсив) в \i. Переменная alias часто используется для совместимости.

См. также макрос.

codeindent

Переменная codeindent указывает уровень отступа, который QDoc использует при записи фрагментов кода.

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

codeprefix, codesuffix

Переменные codeprefix и codesuffix задают пару строк, в которые заключен каждый фрагмент кода.

defines

Переменная defines задает символы препроцессора C++, которые QDoc будет распознавать и на которые будет реагировать.

Когда символ препроцессора задается с помощью переменной defines, вы также можете использовать команду \if для включения документации, которая будет включена только в том случае, если символ препроцессора определен.

Значения переменной представляют собой регулярные выражения (см. QRegularExpression для получения подробностей). По умолчанию ни один символ не определен, что означает, что код, защищенный с помощью #ifdef...#endif, будет проигнорирован.

defines = Q_QDOC \
          QT_.*_SUPPORT \
          QT_.*_LIB \
          QT_COMPAT \
          QT3_SUPPORT \
          Q_OS_.* \
          Q_BYTE_ORDER \
          __cplusplus

Это гарантирует, что QDoc обработает код, для которого необходимо определение этих символов. Например:

#ifdef Q_OS_WIN
  HDC getDC() const;
  void releaseDC(HDC) const;
#endif

Поскольку регулярное выражение Q_OS_.* (заданное с помощью переменной defines), соответствует Q_OS_WIN, QDoc обработает код внутри #ifdef и #endif в нашем примере.

Вы также можете определить символы препроцессора вручную в командной строке с помощью опции -D. Например:

currentdirectory$ qdoc -Dqtforpython qtgui.qdocconf

В этом случае опция -D гарантирует, что символ препроцессора qtforpython будет определен, когда QDoc обрабатывает исходные файлы, определенные в файле qtgui.qdocconf.

См. также falsehoods и \if.

depends

Переменная depends определяет список других проектов документации, от которых зависит этот проект для разрешения целевых ссылок на наследование типов и всего остального, что документация должна связывать.

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

При генерации QDoc документации для проекта также будет создан файл .index содержащий URL-адреса для каждой связанной сущности в проекте. Каждая зависимость — это (маленькая) имя проекта. Это имя должно совпадать с базовым именем файла индекса, сгенерированного для этого проекта.

depends = \
    qtdoc \
    qtcore \
    qtquick

При вызове QDoc для проекта, имеющего зависимости и использующего переменную depends, один или несколько -indexdir путей(ов) должны быть переданы в качестве командной строки. QDoc использует эти пути для поиска файлов индексов зависимостей.

qdoc mydoc.qdocconf -outputdir $PWD/html -indexdir $QT_INSTALL_DOCS

В приведенном выше примере QDoc будет искать файл $T_INSTALL_DOCS/qtdoc/qtdoc.index для зависимости от qtdoc. Если файл индекса для зависимости не найден, QDoc выведет предупреждение.

Команда depends также принимает специальное значение «*». Это указывает QDoc загрузить все файлы индексов, найденные в указанных каталогах индексов; то есть «зависит от всего».

depends = *

См. также индексы, проект и url.

exampledirs

Переменная exampledirs указывает каталоги, содержащие исходный код файлов примеров.

Переменные examples и exampledirs используются командами \quotefromfile, \quotefile и \example. Если переменные examples и exampledirs определены, QDoc будет искать в обоих, сначала в examples, а затем в exampledirs.

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

exampledirs = $QTDIR/doc/src \
              $QTDIR/examples \
              $QTDIR \
              $QTDIR/qmake/examples

examples    = $QTDIR/examples/widgets/analogclock/analogclock.cpp

При обработке

\quotefromfile widgets/calculator/calculator.cpp

QDoc проверит, есть ли файл с именем calculator.cpp в качестве значения в переменной examples. Если его нет, он будет искать в переменной exampledirs, и в первую очередь проверит, существует ли файл с именем

$QTDIR/doc/src/widgets/calculator/calculator.cpp

Если его нет, QDoc продолжит поиск файла с именем

$QTDIR/examples/widgets/calculator/calculator.cpp

и так далее.

См. также examples.

examples

Переменная examples позволяет указать отдельные файлы примеров помимо файлов, расположенных в каталогах, указанных в переменной exampledirs.

Переменные examples и exampledirs используются командами \quotefromfile, \quotefile и \example. Если обе переменные examples и exampledirs определены, QDoc будет искать в обоих, сначала в examples, а затем в exampledirs.

QDoc будет искать через значения, указанные для переменной examples в заданном порядке и примет первое найденное значение.

Для подробного примера см. команду exampledirs. Обратите внимание, что если вы знаете, что файл указан в переменной examples, вам не нужно указывать его путь:

\quotefromfile calculator.cpp

См. также exampledirs.

examples.fileextensions

Переменная examples.fileextensions указывает расширения файлов, которые QDoc будет искать при сборе файлов примеров для отображения в документации.

По умолчанию расширения — *.cpp, *.h, *.js, *.xq, *.svg, *.xml и *.ui.

Расширения задаются в виде стандартных выражений с подстановочными знаками. Вы можете добавить расширение файла к фильтру с помощью '+='. Например:

examples.fileextensions += *.qrc

См. также headers.fileextensions.

excludedirs

Переменная excludedirs предназначена для перечисления каталогов, которые не должны обрабатываться QDoc, даже если те же каталоги включены в переменные sourcedirs или headerdirs.

Например:

sourcedirs =  src/corelib
excludedirs = src/corelib/tmp

При выполнении QDoc исключит указанные каталоги из дальнейшего рассмотрения. Файлы в этих каталогах не будут читаться QDoc.

См. также excludefiles.

excludefiles

Переменная excludefiles позволяет указать отдельные файлы, которые не должны обрабатываться QDoc.

excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \
                $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cpp

Если вы включите вышесказанное в свой файл qdocconf для qtbase, документация класса QWidget не будет сгенерирована.

С Qt 5.6 переменная excludefiles также распознает простые подстановочные знаки ('*' и '?'). Например, чтобы исключить все частные заголовочные файлы Qt из анализа, определите следующее:

excludefiles += "*_p.h"

См. также excludedirs.

extraimages

Переменная extraimages указывает QDoc на включение определенных изображений в сгенерированную документацию.

QDoc не будет распознавать изображения, используемые в HTML (или любом другом языке разметки). Если мы хотим скопировать изображения из каталогов, указанных в imagedirs (изображения должны находиться в этих каталогах) в выходной каталог, мы должны указать изображения с помощью переменной extraimages.

Общий синтаксис extraimages.format = image. Расширение файла необязательно.

Например, в qtgui.qdocconf мы используем несколько изображений в переменной HTML.postheader, значение которой — чистый HTML. Поэтому эти изображения задаются с помощью переменной extraimages:

extraimages.HTML = qt-logo

См. также images и imagedirs.

falsehoods

Переменная falsehoods определяет истинное значение указанных символов препроцессора как ложное.

Значения переменной представляют собой регулярные выражения (см. QRegularExpression для получения подробностей). Если эта переменная не задана для символа препроцессора, QDoc предполагает, что её истинное значение равно true. Исключением является '0', которое всегда ложно.

QDoc распознает и может оценить следующий синтаксис препроцессора:

#ifdef NOTYET
 ...
#endif

#if defined (NOTYET)
 ...
#end if

Однако, столкнувшись с неизвестным синтаксисом, таким как

#if NOTYET
    ...
#endif

QDoc по умолчанию оценит его как true, за исключением случаев, когда символ препроцессора указан в falsehoods записи переменной:

falsehoods = NOTYET

См. также defines.

generateindex

Переменная generateindex содержит булево значение, определяющее, нужно ли генерировать файл индекса при создании HTML-документации.

По умолчанию файл индекса всегда генерируется с HTML-документацией, поэтому эта переменная обычно используется только при отключении этой функции (установкой значения в false) или при включении генерации индекса для вывода WebXML (установкой значения в true).

headerdirs

Переменная headerdirs указывает каталоги, содержащие заголовочные файлы, связанные с .cpp исходными файлами, используемыми в документации.

headerdirs = $QTDIR/src \
             $QTDIR/extensions/activeqt \
             $QTDIR/extensions/motif \
             $QTDIR/tools/designer/src/lib/extension \
             $QTDIR/tools/designer/src/lib/sdk \
             $QTDIR/tools/designer/src/lib/uilib

При выполнении QDoc в первую очередь прочитает заголовки, указанные в переменной headers, и расположенные в каталогах, указанных в переменной headerdir (включая все подкаталоги), создавая внутреннюю структуру классов и их функций.

Затем он прочитает исходные файлы, указанные в sources, и расположенные в каталогах, указанных в sourcedirs переменной (включая все подкаталоги), объединяя документацию со структурой, полученной из заголовочных файлов.

Если обе переменные headers и headerdirs определены, QDoc прочитает оба, сначала headers, затем headerdirs.

В указанных каталогах QDoc будет читать только файлы с расширениями, указанными в headers.fileextensions переменной. По умолчанию расширения — *.ch, *.h, *.h++, *.hh, *.hpp и *.hxx. Файлы, указанные в headers, будут читаться без учёта расширений файлов.

См. также headers и headers.fileextensions.

headers

Переменная headers позволяет указать отдельные заголовочные файлы помимо тех, которые находятся в каталогах, указанных в headerdirs переменной.

headers = $QTDIR/src/gui/widgets/qlineedit.h \
          $QTDIR/src/gui/widgets/qpushbutton.h

При обработке переменной headers QDoc ведет себя так же, как и при обработке переменной headerdirs. Для получения дополнительной информации см. переменную headerdirs.

См. также headerdirs.

headers.fileextensions

Переменная headers.fileextensions указывает расширение, используемое заголовками.

При обработке заголовочных файлов, указанных в переменной headerdirs, QDoc будет читать только файлы с расширениями, указанными в переменной headers.fileextensions. Таким образом, QDoc избегает траты времени на чтение нерелевантных файлов.

По умолчанию расширения — *.ch, *.h, *.h++, *.hh, *.hpp и *.hxx.

Расширения задаются в виде стандартных выражений с подстановкой. Вы можете добавить расширение файла к фильтру, используя '+='. Например:

header.fileextensions += *.H

Предупреждение: Вышеприведенное присваивание может работать не так, как описано.

См. также headerdirs.

ignorewords

Переменная ignorewords используется для указания списка строк, которые QDoc будет игнорировать при разрешении целевых ссылок гиперссылок.

QDoc имеет функцию автоматической привязки, где попытка привязки осуществляется для слов, напоминающих сущности C++, QML или JavaScript. В частности, строка подходит для автоматической привязки, если её длина не менее трёх символов, в ней нет пробелов и она

• является словом camelCase, то есть содержит по крайней мере один символ верхнего регистра с индексом больше нуля, или
• содержит подстроку () или ::, или
• содержит по крайней мере один специальный символ, @ или _.

Добавление квалифицированного слова в ignorewords останавливает автоматическую привязку QDoc для этого слова. Например, если слово OpenGL является допустимой целью ссылки (раздел, \page, или \externalpage заголовок), гиперссылка для каждого вхождения может быть предотвращена с помощью

ignorewords += OpenGL

Явное создание ссылок с помощью \l продолжает работать для игнорируемых слов.

Переменная ignorewords была введена в QDoc 5.14.

ignoresince

Переменная ignoresince используется для установки значения отсечения для версий, передаваемых команде \since. Все команды \since, которые определяют версию ниже значения отсечения, игнорируются и не генерируют вывод.

Значения отсечения зависят от проекта. Название проекта может быть определено как подпеременная. По умолчанию имя проекта — Qt. Например:

ignoresince      = 5.0
ignoresince.QDoc = 5.0

Эти команды проигнорируют команды \since, где основная версия — 4 или ниже, а проект — QDoc или не определён.

\since 3.2          # Ignored
\since 5.2          # Documented (as 'Qt 5.2')
\since QDoc 4.6     # Ignored
\since QtQuick 2.5  # Documented

Переменная ignoresince была введена в QDoc 5.15.

См. также \since.

imagedirs

Переменная imagedirs указывает каталоги, содержащие изображения, используемые в документации.

Переменные images и imagedirs используются командами \image и \inlineimage. Если обе переменные images и imagedirs определены, QDoc будет искать в обоих. Сначала в images, затем в imagedirs.

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

imagedirs = $QTDIR/doc/src/images \
            $QTDIR/examples

images    = $QTDIR/doc/src/images/calculator-example.png

При обработке

\image calculator-example.png

QDoc проверит, есть ли файл под названием calculator-example.png в качестве значения в переменной images. Если нет, он будет искать в переменной imagedirs файл:

$QTDIR/doc/src/images/calculator-example.png

Если файл не существует, QDoc будет искать файл под названием

$QTDIR/examples/calculator-example.png

Вы можете отфильтровать изображения в каталоге изображений, используя переменную images.fileextensions. Основная идея переменной images.fileextensions заключается в возможности использования разных форматов изображений для разных форматов вывода.

Предупреждение: Функциональность переменной images.fileextensions является предварительной, так как QDoc на данный момент поддерживает только HTML.

См. также images и images.fileextensions.

images

Переменная images позволяет указать отдельные файлы изображений помимо тех, которые находятся в каталогах, указанных в imagedirs переменной.

images = $QTDIR/doc/src/images/calculator-example.png

При обработке переменной images QDoc ведет себя так же, как и при обработке переменной imagedirs. Для получения дополнительной информации см. переменную imagedirs.

См. также imagedirs и images.fileextensions.

images.fileextensions

Переменная images.fileextensions фильтрует файлы в каталоге изображений.

Значения переменной (расширения) задаются в виде стандартных выражений с подстановкой. Общий синтаксис: images.fileextensions.format = *.extension.

Идея заключается в том, чтобы включить разные форматы изображений для различных форматов вывода.

images.fileextensions.HTML = *.png
images.fileextensions.LOUT = *.eps

Затем, при обработке команд \image и \inlineimage, QDoc будет искать только файлы с расширениями, указанными в переменной, содержащей список форматов вывода.

Предупреждение: Это лишь предварительная функциональность, поскольку QDoc на данном этапе поддерживает только HTML.

По умолчанию для HTML расширения — *.png, *.jpg, *.jpeg и *.gif.

Вы можете добавить расширение файла к фильтру, используя '+='. Например:

images.fileextensions.HTML += *.eps

См. также imagedirs и images.

language

Переменная language указывает язык исходного кода, используемого в документации.

В настоящее время QDoc понимает только язык C++. Он также является языком по умолчанию и фактически не нуждается в указании. Однако возможный пример оператора переменной языка:

language = Cpp

Это определяет C++ как язык исходного кода Qt.

locationinfo

Булевая переменная locationinfo определяет, нужно ли записывать подробную информацию о местоположении каждой сущности в файлы .index и .webxml (при использовании формата вывода WebXML).

Информация о местоположении состоит из полного пути и номера строки либо блока объявления, либо блока комментариев документации в исходном коде.

Установка этого значения в false отключает информацию о местоположении:

locationinfo = false

Значение по умолчанию равно true.

Переменная locationinfo была введена в QDoc 5.15.

макрос

Переменная macro используется для создания собственных простых команд QDoc. Синтаксис — macro.command = definition, где определение записывается с использованием синтаксиса QDoc.

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

macro.gui              = "\\b"
macro.raisedaster.HTML = "<sup>*</sup>"

Первый макрос определяет команду \gui для рендеринга ее аргумента с использованием полужирного шрифта. Второй макрос определяет команду \raisedaster для рендеринга надстрочного знака звездочки, но только при генерации HTML.

Макрос также может принимать до семи параметров:

macro.hello            = "Hello \1!"

Параметры передаются макросам так же, как и другим командам:

\hello World

При использовании более одного параметра или когда аргумент содержит пробелы, заключите каждый аргумент в фигурные скобки:

macro.verinfo          = "\1 (version \2)"

\verinfo {QFooBar} {1.0 beta}

Для расширенных макросов можно добавить специальный параметр макроса match для дополнительного сопоставления с регулярными выражениями.

Например,

macro.qtminorversion       = "$QT_VER"
macro.qtminorversion.match = "\\d+\\.(\\d+)"

Это создает макрос \qtminorversion, который расширяется до значений младшей версии, основанной на переменной среды QT_VER.

Макрос, определяющий шаблон сопоставления, выводит все группы захвата (скобки), соединенные вместе, или точное совпадающее значение, если шаблон не содержит групп захвата.

См. также псевдоним.

manifestmeta

Переменная manifestmeta указывает дополнительное метасодержимое для файлов манифеста примера, сгенерированных QDoc.

См. раздел Метасодержимое манифеста для получения дополнительной информации.

естественный язык

Переменная naturallanguage указывает естественный язык, используемый для документации, сгенерированной QDoc.

naturallanguage = zh-Hans

По умолчанию естественный язык равен en для совместимости со старой документацией.

QDoc добавит информацию о естественном языке в генерируемый HTML, используя атрибуты lang и xml:lang.

См. также sourceencoding, outputencoding, C.7. Атрибуты lang и xml:lang и Рекомендация 13: Использование кодов Hans и Hant.

навигация

Подчиненные переменные navigation, если они определены, устанавливают домашнюю страницу, целевую страницу, страницу классов C++ и страницу типов QML, которые отображаются в генерируемой навигационной панели для каждой страницы.

В проекте с несколькими подпроектами (например, модулями Qt) каждый подпроект обычно определяет свою собственную целевую страницу, в то время как домашняя страница используется во всех подпроектах.

Подчиненные переменные

Например:

# Common configuration
navigation.homepage  = index.html
navigation.hometitle = "Qt $QT_VER"

# qtquick.qdocconf
navigation.landingpage    = "Qt Quick"
navigation.cppclassespage = "Qt Quick C++ Classes"
navigation.qmltypespage   = "Qt Quick QML Types"

Вышеуказанная конфигурация создает следующую навигационную панель для типа Item QML:

Qt 5.10 > Qt Quick > QML Types > Item QML Type

outputdir

Переменная outputdir указывает каталог, в который QDoc поместит сгенерированную документацию.

outputdir = $QTDIR/doc/html

располагает сгенерированную документацию Qt Reference в $QTDIR/doc/html. Например, документация класса QWidget расположена в

$QTDIR/doc/html/qwidget.html

Сопутствующие изображения будут помещены в подкаталог images.

Предупреждение: При многократном запуске QDoc с использованием одного и того же каталога вывода все файлы из предыдущего выполнения будут потеряны.

outputencoding

Переменная outputencoding указывает кодировку, используемую для сгенерированной QDoc документации.

outputencoding = UTF-8

По умолчанию кодировка вывода — ISO-8859-1 (Latin1) для совместимости со старой документацией. При генерации документации для некоторых языков, особенно для языков, не относящихся к европейским языкам, этого недостаточно, и необходима кодировка, такая как UTF-8.

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

См. также outputencoding и naturallanguage.

outputformats

Переменная outputformats указывает формат(ы) сгенерированной документации.

Начиная с Qt 5.11, QDoc поддерживает форматы HTML и WebXML; начиная с Qt 5.15, он также может генерировать документацию в формате DocBook. Если outputformats не указаны, QDoc генерирует документацию в формате HTML (формат по умолчанию). Все форматы вывода могут быть указаны с выделенными каталогами вывода и другими настройками. Например:

outputformats = WebXML HTML
WebXML.nosubdirs = true
WebXML.outputsubdir = webxml
WebXML.quotinginformation = true

Это генерирует HTML-документацию с использованием значений по умолчанию, а также WebXML-документацию в подкаталоге webxml.

outputprefixes

Переменная outputprefixes указывает сопоставление между типами файлов и префиксами, которые будут добавлены к именам HTML-файлов в сгенерированной документации.

outputprefixes     = QML JS
outputprefixes.QML = uicomponents-
outputprefixes.JS  = uicomponents-

По умолчанию файлы, содержащие документацию API для типов QML, имеют префикс "qml-", а для типов javaScript — "js-". В приведенном выше примере префикс "uicomponents" используется вместо этого для обоих.

Префикс вывода применяется к именам файлов для документации по типам QML и JS.

outputsuffixes

Переменная outputsuffixes указывает сопоставление между типами файлов и суффиксами имен модулей, которые будут добавлены к именам HTML-файлов.

outputsuffixes     = QML
outputsuffixes.QML = -tp

При имени модуля QML FooBar и по умолчанию префиксу вывода ("qml-"), имя файла генерируемой HTML-страницы для типа QML FooWidget будет qml-foobar-tp-foowidget.html.

По умолчанию суффикс не используется. Суффикс вывода, если он определен, применяется к именам файлов для документации по типам QML и JS, а также к страницам их соответствующих модулей.

Переменная outputsuffixes была введена в QDoc 5.6.

qhp

Переменная qhp используется для определения информации, которая будет записана в файлы Qt Help Project (qhp).

См. главу Создание файлов проекта справки для получения информации об этом процессе.

sourcedirs

Переменная sourcedirs указывает каталоги, содержащие файлы .cpp или .qdoc , используемые в документации.

sourcedirs  += .. \
               ../../../examples/gui/doc/src

При выполнении QDoc в первую очередь прочитает заголовки, указанные в переменной header, а также расположенные в каталогах, указанных в переменной headerdir (включая все подкаталоги), создавая внутреннюю структуру классов и их функций.

Затем он прочитает источники, указанные в sources, а также расположенные в каталогах, указанных в переменной sourcedirs (включая все подкаталоги), объединяя документацию со структурой, полученной из файлов заголовков.

Если определены обе переменные sources и sourcedirs, QDoc прочитает оба, сначала sources, затем sourcedirs.

В указанных каталогах QDoc будет считывать только файлы с расширениями fileextensions, указанными в sources.fileextensions переменной. Расширения по умолчанию — *.c++, *.cc, *.cpp и *.cxx. Файлы, указанные в sources, будут читаться независимо от их расширений.

См. также sources и sources.fileextensions.

sourceencoding

Переменная sourceencoding указывает кодировку, используемую для исходного кода и документации.

sourceencoding = UTF-8

По умолчанию кодировка исходного текста — ISO-8859-1 (Latin1) для совместимости со старой документацией. Для некоторых языков, особенно неевропейских, этого недостаточно, и требуется кодировка, например, UTF-8.

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

См. также naturallanguage и outputencoding.

sources

Переменная sources позволяет указать отдельные исходные файлы помимо тех, которые находятся в каталогах, указанных переменной sourcedirs.

sources = $QTDIR/src/gui/widgets/qlineedit.cpp \
          $QTDIR/src/gui/widgets/qpushbutton.cpp

При обработке переменной sources QDoc ведет себя так же, как и при обработке переменной sourcedirs. Дополнительную информацию см. в переменной sourcedirs.

См. также sourcedirs.

sources.fileextensions

Переменная sources.fileextensions фильтрует файлы в каталоге исходных файлов.

При обработке исходных файлов, указанных в переменной sourcedirs, QDoc будет читать только файлы с расширениями, указанными в переменной sources.fileextensions. Таким образом, QDoc избегает траты времени на чтение нерелевантных файлов.

По умолчанию расширения — *.c++, *.cc, *.cpp и *.cxx.

Расширения задаются в виде стандартных выражений подстановки. Вы можете добавить расширение файла к фильтру, используя '+='. Например:

sources.fileextensions += *.CC

Предупреждение: Вышеприведённое присваивание может работать не так, как описано.

См. также sourcedirs и sources.

spurious

Переменная spurious исключает указанные предупреждения QDoc из вывода. Предупреждения задаются с использованием стандартных выражений подстановки.

spurious = "Cannot find .*" \
"Missing .*"

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

src/opengl/qgl_mac.cpp:156: Missing parameter name

syntaxhighlighting

Переменная syntaxhighlighting указывает, должен ли QDoc выполнять подсветку синтаксиса исходного кода, цитируемого в генерируемой им документации.

syntaxhighlighting = true

включит подсветку синтаксиса для всех поддерживаемых языков программирования.

tabsize

Переменная tabsize определяет размер символа табуляции.

tabsize = 4

присвоит символу табуляции размер в 4 пробела. Значение по умолчанию — 8, и его не нужно указывать.

tagfile

Переменная tagfile указывает файл тегов Doxygen, который должен быть записан при генерации HTML.

version

Переменная version указывает номер версии документированного программного обеспечения.

version = 5.6.0

Когда номер версии указан (с помощью переменных version или versionsym в файле .qdocconf), к нему можно получить доступ через соответствующую команду \version для использования в документации.

Предупреждение: Функциональность команды \version не полностью реализована; в настоящее время она работает только внутри исходного кода HTML.

См. также versionsym.

versionsym

Переменная versionsym указывает символ препроцессора C++, определяющий номер версии документированного программного обеспечения.

versionsym = QT_VERSION_STR

QT_VERSION_STR определен в qglobal.h следующим образом

#define QT_VERSION_STR   "5.14.1"

Когда номер версии указан (с помощью переменных version или versionsym в файле .qdocconf), к нему можно получить доступ через соответствующую команду \version для использования в документации.

Предупреждение: Функциональность команды \version не полностью реализована. В настоящее время она работает только внутри исходного кода HTML.

См. также \version.

warninglimit

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

Установка warninglimit в 0 означает сбой при любом предупреждении.

Примечание: По умолчанию QDoc не проверяет предел предупреждений. Включите его с помощью warninglimit.enabled = true или задав переменную среды QDOC_ENABLE_WARNINGLIMIT.

Например,

# Fail the documentation build if we have more than 100 warnings
warninglimit = 100
warninglimit.enabled = true

Переменная warninglimit была добавлена в Qt 5.11.