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

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

depends = \
    qtdoc \
    qtcore \
    qtquick

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

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

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

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

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 предполагает его истинностное значение как истинное. Исключение — «0», которое всегда ложно.

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

#ifdef NOTYET
 ...
#endif

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

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

#if NOTYET
    ...
#endif

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

falsehoods = NOTYET

См. также определения.

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.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.

includepaths

Переменная includepaths используется для передачи дополнительных путей включения парсеру Clang, который QDoc использует для разбора кода C++ с комментариями документации.

Переменная принимает список путей, префикс которых -I (путь включения), -F (путь включения фреймворка macOS) или -isystem (систематический путь включения). Если префикс опущен, по умолчанию используется -I.

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

См. также moduleheader.

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.

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

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

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

images.fileextensions.HTML += *.eps

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

язык

Переменная 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.

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

См. также alias.

manifestmeta

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

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

moduleheader

Переменная moduleheader определяет имя заголовка модуля документированного модуля C++.

Проекты, документирующие API C++, требуют заголовка уровня модуля, который включает все публичные классы, пространства имен и заголовочные файлы модуля. Парсер Clang в QDoc использует этот файл для построения предварительно скомпилированного заголовка (PCH) для модуля, чтобы ускорить парсинг исходных файлов.

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

project = QtCore

При указанном имени проекта QDoc ищет заголовок модуля QtCore во всех известных путях включения, сначала используя пути, переданные в качестве аргументов командной строки, а затем пути, указанные в переменной includepaths.

Если заголовок модуля не найден, QDoc выведет предупреждение. Затем он попытается создать искусственный заголовок модуля на основе заголовков, перечисленных в переменной headerdirs.

Для проектов документации Qt система сборки обычно предоставляет QDoc правильные пути включения для поиска заголовка модуля при условии, что переменная project настроена правильно. Переменная moduleheader предоставляет альтернативное имя файла для поиска QDoc.

Если проект не содержит документации C++, QDoc следует инструктировать пропустить генерацию PCH, установив moduleheader в пустую строку:

# No C++ code to document in this project
moduleheader =

См. также includepaths и project.

naturallanguage

Переменная 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 по ссылке $QTDIR/doc/html. Например, документация класса QWidget находится по адресу

$QTDIR/doc/html/qwidget.html

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

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 (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-variable} {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 для использования в документации.

См. также 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.

warninglimit

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

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

Например,

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

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