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

С помощью общих переменных конфигурации 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 распределена по нескольким модулям. В проекте документации с несколькими модулями минимальный набор зависимостей для одного модуля состоит из фактических зависимостей сборки. Кроме того, если есть проект документации (модуль), который является точкой входа на верхнем уровне для всего набора документации и предоставляет ссылки navigation-variable[navigation}, каждая документация модуля должна включать его в качестве зависимости.

При генерации документации 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 = *

См. также indexes, project и 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 будет читать только файлы с расширениями, указанными в переменной 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.