Как устранить предупреждения QDoc

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

Не удаётся создать ссылку на <target>

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

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

Если цель ссылки похожа на имя типа или функции, это также может быть из-за:

• Имя (или, в случае функций, указанная сигнатура), используемое в документации, не совпадает с именем, используемым в объявлении.
• Цель ссылки помечена как \internal, а текст ссылки — нет.

Файл фрагмента кода не найден

QDoc выдает это предупреждение, если не может найти файл, указанный в команде \snippet или \quotefromfile.

Некоторые полезные шаги для исправления:

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

Неожиданная команда \snippet

QDoc выдает это предупреждение, если не может найти файл фрагмента, указанный в команде \snippet.

Недокументированное значение возврата

Для функций, тип возвращаемого значения которых не void, QDoc проверяет, документировано ли значение возврата. Это предупреждение выдается, если в документации функции или метода нет слова, начинающегося с «return».

Недокументированный параметр

QDoc требует документации функции или метода, описывающей каждый параметр. Она распознаёт это, если каждое имя параметра (как указано в объявлении функции или метода в заголовочном файле) появляется после команды \a.

Параметр не найден

QDoc выдает это предупреждение, когда имя параметра, указанное после команды \a, не соответствует ни одному из параметров, указанных в объявлении функции или метода в заголовочном файле.

Неизвестный макрос

QDoc выдает это предупреждение, когда видит обратный слэш, \, за которым следует маркер, который не распознаётся как имя встроенной команды или пользовательского макроса. При цитировании кода, содержащего последовательности escape-символов, следует заключать код в \c{...} для предотвращения предупреждений о последовательностях escape-символов.

Clang не нашёл функцию при разборе \fn <signature>

При разборе Clang инструкции функции после \fn проверяет её против объявления в заголовочном файле. Если Clang обнаруживает расхождения, выдаётся это сообщение о предупреждении.

Класс C++ <ClassName> не найден: \instantiates <ClassName>

Если вы описываете тип QML, вы можете указать класс, который он создаёт. Обратитесь к команде \instantiates в руководстве QDoc.

Невозможно связать эту документацию ни с чем

QDoc нашёл комментарий \beginqdoc ... \endqdoc без команды темы, который не был сразу после объявления класса, функции или свойства. Таким образом, он не знает, что документирует комментарий.

В этом комментарии QDoc нет команды темы (например, \module, \page)

Если в комментарии QDoc нет команды темы, QDoc не знает, что документирует комментарий, и выдает это предупреждение. Очень похоже на Невозможно связать эту документацию ни с чем, но конкретно для комментариев, которые не находятся в файлах C++ или QML.

<name> документирован более одного раза (предыдущая документация здесь)

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

Например, вы видите это предупреждение, когда функция имеет комментарий документации перед своим определением и отдельный комментарий \fn в другом месте.

Пространство имен <name> документировано более одного раза

Это предупреждение означает, что набор документации содержит два комментария, содержащие команды \namespace с одним и тем же аргументом <name>.

<name> документирован, но пространство имен <namespace> не документировано ни в одном модуле

Документация для <name> найдена, но <name> объявлена в пространстве имен, которое не документировано или QDoc не смог найти документацию для него.

Это можно исправить, либо документировав <namespace>, или, если оно уже документировано в другом модуле, убедитесь, что этот модуль зависит от него.

См. также depends и {indexes-variable}{indexes}.

Clang не смог найти функцию при разборе \fn <signature>

При разборе команды \fn, Clang сравнивает её с объявлением функции в заголовочном файле. Если сигнатура отличается, Clang выдает это предупреждение.

• Член класса или пространства имен должен включать префикс класса или пространства имен в имени члена.
• \fn без типа возвращаемого значения соответствует независимо от фактического типа возвращаемого значения, но если он указывает неверный тип возвращаемого значения, он не соответствует.
• Различия в именах параметров в \fn не препятствуют соответствию, хотя команды \a в комментарии должны использовать имена из объявления.

Нет команды \inmodule

QDoc выдает это предупреждение, если комментарии QDoc не связывают класс, пространство имен или заголовочный файл с модулем с помощью команды \inmodule.

Если комментарий QDoc описывает сущность, которая не является членом другой сущности (обычно пространства имен или класса), следует использовать либо \relates, либо \inmodule, чтобы связать её с её более широким контекстом. Это предупреждение выдается, если этого не сделано.

Невозможно найти <name>, указанный с помощью <command>, в любом заголовочном файле

Это означает, что QDoc не может найти объявление <name> в любом заголовочном файле, но нашёл комментарий, который утверждает, что документирует его.

Пример:

Cannot find 'Color::Red' specified with '\enum' in any header file.

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

Это также может быть из-за:

• опечатки в <name> или <command>
• отсутствующего префикса пространства имён или класса
• <name> был перемещён в другое пространство имён или класс

Нераспознанный квалификатор модуля/компонента QML для <identifier>

Параметр, переданный в \qmlproperty или \qmlmethod, содержит комбинацию qmlModule::qmlType::identifier, которая нигде не определена.

Пример:

Unrecognizable QML module/component qualifier for real QtQuick::DragHandler::DragAxis::minimum

DragHandler не имеет свойства DragAxis.

Отсутствует тип свойства для <name>

Объявление \qmlproperty отсутствует тип свойства.

Команда \qmlproperty ожидает, что за ней последует тип свойства, а затем полностью квалифицированное имя свойства (т.е. имя, соединённое с помощью :: после имени класса, к которому оно принадлежит).

Неправильно:

\qmlproperty MyWidget::count

Правильно:

\qmlproperty int MyWidget::count

Свойство QML документировано несколько раз: <identifier>

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

Команда <command> запрещена для команд свойств QML/JS

Пример:

\qmlproperty real QtQuick.Controls::RangeSlider::first.value
\qmlproperty real QtQuick.Controls::RangeSlider::first.position
\qmlproperty real QtQuick.Controls::RangeSlider::first.visualPosition
\qmlsignal void QtQuick.Controls::RangeSlider::first.moved()
\qmlsignal void QtQuick.Controls::RangeSlider::second.moved()

Сообщение об ошибке:

Command '\\qmlsignal' not allowed with QML/JS property commands

Это предупреждение специфично для документации групп свойств. QDoc разрешает несколько команд темы (qml|js)property или (qml|js)attachedproperty в одном комментарии документации для документирования группы свойств, где последним элементом в пути является <group>.<property>. Любая другая команда темы вызывает это предупреждение.

Не найдена базовая функция для метода <method> в классе <class>

QDoc выдает это предупреждение, если \reimp используется для документирования метода, как переопределения виртуального метода, когда у базового класса нет виртуального метода с заданным именем и сигнатурой. Это может произойти, потому что метод, который он должен был переопределить, изменил свою сигнатуру или больше не является виртуальным.

Незаконная команда \reimp; нет документированной виртуальной функции для <command>

Qdoc пытается создать ссылку на функцию, которую эта функция переопределяет, но не смог найти целевой объект ссылки, вероятно, потому что эта функция не документирована. Это также может произойти, если ни один базовый класс не имеет виртуального метода с этим именем и сигнатурой; это может произойти из-за переименования, изменения сигнатуры или того, что базовый класс больше не объявляет его виртуальным.

<класс> пытается унаследовать самого себя

Команда \inherits используется для документирования того, что тип QMl наследует какой-либо другой тип QML. Это предупреждение выдаётся, если этот другой тип QML совпадает с документируемым типом QML.

Пример:

\qmltype Foo
\inherits Foo

\instantiates разрешена только в \qmltype

Команда \instantiates может быть использована только в комментарии QDoc, документирующем тип QML.

Все свойства в группе должны принадлежать одному и тому же типу: <имя>

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

Не удаётся найти файл проекта для примера <имя>

В каталоге исходного кода примера QDoc ожидает найти файл проекта с именем CMakeLists.txt, или файл с расширением .pro, .qmlproject, или .pyproject, где базовое имя соответствует имени каталога примера. Например, examples/mymodule/helloworld/helloworld.pro.

Имя команды <псевдоним> не может обозначать одновременно <первое> и <последующее>

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

Не удаётся открыть файл для цитирования: <имя_файла>

Путь поиска для <имя_файла> определяется следующими переменными в файле .qdocconf: sources, sourcedirs, и exampledirs.

QDoc не смог найти файл, указанный в команде (например, \quotefromfile, \snippet, \include), которая указывает на получение содержимого из указанного файла. Он ищет каждый каталог, указанный в пути поиска. Если в каком-либо из этих каталогов нет файла с этим именем, или файл найден, но недоступен для чтения, QDoc выдаёт это предупреждение. Проверьте, что сочетание пути поиска и <имя_файла> написано правильно, и что у вас есть права на чтение для файла.

Отсутствует имя формата после \raw

Команда \raw и соответствующая команда \endraw разграничивают блок исходного кода языка разметки. Команда \raw должна следовать за именем формата. Пока что это может быть только HTML.

Макрос не может иметь как формат-специфические, так и определения синтаксиса qdoc

Макрос \macro, который определяет формат вывода, также не может иметь общее определение.

Пример конфигурации, которая вызывает это предупреждение:

macro.gui = \b
macro.gui.HTML = "<b>\1</b>"

Неизвестная команда <имя>

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

Это также может быть вызвано цитированием кода в комментарии QDoc, например, автор может сослаться на символ завершения строки C '\0' или на одну из других последовательностей escape-символов строки C, таких как '\n' без экранирования обратной косой черты. Экранируйте обратную косую черту как \, чтобы включить буквальную обратную косую черту в документацию, или поместите фрагмент кода в \c{...}, что подавляет интерпретацию обратных косых черт как ввода команд QDoc.

Дублирующееся имя целевого объекта <target>

Это означает, что существуют две команды \target с одинаковым параметром. Они должны быть уникальными. Это предупреждение сопровождается предупреждением «Предыдущее появление здесь».

Не удаётся найти файл включения qdoc <имя_файла>

QDoc не смог найти файл включения, указанный в команде. QDoc ищет каждый каталог, указанный в пути поиска. Если в каком-либо из этих каталогов нет файла с этим именем, или файл, найденный в этом поиске, не доступен для чтения, QDoc выдаёт это предупреждение. Проверьте правильность написания сочетания пути поиска и <имя_файла>, а также наличие прав на чтение для файла.

Не удаётся найти <тег> в <файл>

Это означает, что QDoc не может найти идентификатор <id> в \include <файл> или {snippet-command}{\snippet} <файл>.

Пустой фрагмент qdoc <тег> в <файле>

Фрагмент <тег> был найден в \snippet <файл>, но он пуст.

Нельзя вкладывать команды <команда>

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

There is \b{no \b{super-}bold}.
\encode

\section1 Can't use <inner> in <outer>

This warning is issued for commands that cannot be nested.

Example:
\badcode
    \list
        \li \table
            \row \li Hello \li Hi
            \endtable
    \endlist

Результат в предупреждение QDoc «Нельзя использовать '\table' в '\list'».

Отсутствует <внешний> перед <внутренний>

Некоторые примеры:

• Команда \li может использоваться только внутри \list или \row таблицы \table.
• Команды \row и \header могут использоваться только внутри \table.

Неожиданная команда <end_command>

Это предупреждение выдаётся, если, например, у вас есть \endlist без предшествующей \list. Это относится ко всем командам, которые появляются парами (например, startFoo/endFoo).

Отсутствует запятая в \sa

Заголовки, перечисленные для команды \sa, должны разделяться запятыми.

Макрос <команда> не имеет стандартного определения

QDoc пытается расширить макрос и ожидает, что этот макрос будет иметь стандартное определение. Некоторые макросы могут иметь только формат-специфические определения.

Пример:

macro.pi.HTML = "π"    # encodes the pi symbol for HTML output format

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

Макрос <макрос> вызван с недостаточным количеством аргументов (ожидалось <много>, получено <мало>)

Данный макрос требует больше параметров, чем предоставлено.

Несбалансированные скобки в <тексте>

Указывает на '(' без соответствующего ')', или наоборот.

Отсутствует документация для <имя>

Пример:

Warning "No documentation for QNativeInterface."

QDoc обнаруживает объявление пространства имён QNativeInterface в файле заголовка, но не находит комментарий QDoc, где это пространство имён было документировано.

Нет такого элемента перечисления <имя> в <класс>

Пример:

Cannot find 'QSGMaterialRhiShader::RenderState::DirtyState' specified
with \enum in any header file.

QDoc выдаёт это предупреждение, когда находит директиву \value в комментарии \enum, которая указывает на значение, не найденное в файле заголовка, который объявил документированный перечислимый тип.

Недокументированный элемент перечисления <перечисление> в списке перечислений <список перечислений>

Элементы <список перечислений> \value или \omitvalue не включали одно для <перечисление>, которое указано в объявлении <список перечислений> в файле заголовка.

Не удаётся найти индекс: <имя_файла>

Пример:

Failed to find index: path/to/QtCrator/appmanplugin/manual.index

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

Неправильно:

indexes += path/to/QtCrator/appmanplugin/manual.index

Правильно:

indexes += path/to/QtCreator/appmanplugin/manual.index

\generatelist examplefiles может использоваться только с командой темы \example

Команда «\generatelist examplefiles» может использоваться только в документации примера (то есть, когда команда темы — \example).

\generatelist <группа> пуста

Ниже приведён краткий обзор всех возможных аргументов для \generatelist:

• \generatelist annotatedexamples
• \generatelist annotatedattributions
• \generatelist classes <префикс>
• \generatelist classesbymodule <имя модуля>
• \generatelist qmltypesbymodule <имя модуля>
• \generatelist jstypesbymodule <имя_модуля>
• \generatelist examplesfiles <регулярное выражение>
• \generatelist exampleimages <регулярное выражение>
• \generatelist functionindex
• \generatelist legalese
• \generatelist overviews
• \generatelist attributions
• \generatelist related

QDoc выводит это предупреждение, если вы укажите \generatelist <group> и группа не содержит ни одного элемента, или если вы укажите \generatelist <group> <pattern> и ни один элемент в группе не соответствует шаблону.

\generatelist <group> no such group

Это предупреждение выводится, если аргумент для \generatelist является несуществующей группой.

Пример:

\generatelist draganddrop

Это оператор генерирует список классов или типов QML в группе draganddrop. Классы или типы QML добавляются в группу draganddrop с помощью команды \l {ingroup-command}{\ingroup} draganddrop в их \class или \qmltype комментарии.

QDoc выводит это сообщение об ошибке, если ни один объект не имеет этого \ingroup draganddrop оператора.

Отсутствующее изображение: <imagefile>

Путь к изображению неверный или файл изображения не существует.

Не удается создать ссылку на <target>

Это может быть вызвано различными причинами:

• Целевое место ссылки не было определено с помощью команды QDoc, например {title-command}{\title} <target>.
• В <target> допущена опечатка.
• Документ, содержащий целевой объект ссылки, не был скомпилирован.
• Документ, содержащий целевой объект ссылки, находится в модуле, который не входит в путь компиляции.
• Целевой объект ссылки находится в другом модуле, и зависимость от этого модуля не была установлена в конфигурации, или QDoc не смог найти файл индекса для зависимости.

Не удалось разрешить оператор импорта QML для типа <name>

QDoc выводит это предупреждение, если вы документируете тип QML, но опускаете команду \inqmlmodule. Пример:

Could not resolve QML import statement for type 'ItemSelectionModel'
\encode

Incorrect:
  \badcode
  \qmltype ItemSelectionModel
  \instantiates QItemSelectionModel
  \since 5.5
  \ingroup qtquick-models

Правильно:

\qmltype ItemSelectionModel
\instantiates QItemSelectionModel
\inqmlmodule QtQml.Models
\since 5.5
\ingroup qtquick-models

\brief statement does not end with a full stop

Аргумент команды \brief — это предложение, кратко описывающее тему, которая документируется, поэтому оно должно заканчиваться точкой. Оно также должно быть кратким.

QtDeclarative не установлен; невозможно проанализировать QML или JS

QDoc выводит это предупреждение, если он был скомпилирован без поддержки анализа QML/JS. Этого не должно произойти, если только у вас нет пользовательской сборки QDoc.

Неправильное регулярное выражение <regex>

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

Пример:

notifications.qdoc:56: (qdoc) warning: Invalid regular expression '^})$'

\quotefromfile webenginewidgets/notifications/data/index.html
\skipuntil resetPermission

Неправильное регулярное выражение:

\printuntil /^})$/

Правильное регулярное выражение:

\printuntil /^\}\)$/

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

Найдено несколько файлов индекса для зависимости <indexfile>:<depend>

Использование <indexfile> в качестве файла индекса для зависимости <depend>

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

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

Невозможно найти файл индекса для зависимости <depend>

Пример:

"QMake" Cannot locate index file for dependency "activeqt"

Проект документации QMake не смог найти activeqt.index в любом из указанных каталогов индексов. В этом случае указанные каталоги индексов определены в qmake.qdocconf.

Указаны зависимые модули, но каталоги индексов не были установлены.

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

Заменяет предыдущий документ (Предыдущий документ находится здесь)

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

Неизвестный стиль списка <name>

\list может принимать необязательный аргумент: одно число или символ, который изменяет стиль списка. Подробнее см. документацию {list-command}{\list}. Если вы используете аргумент, который не распознается, QDoc выводит это предупреждение.

Невозможно проанализировать фрагмент QML: <code> на строке <y>, столбец <x>

Комментарии QDoc могут содержать код QML. Этот код может находиться в фрагменте или в комментариях QDoc, ограниченных \qml и {endqml-command}{\endqml}.

Пример:

Если в коде QML есть синтаксическая ошибка, QDoc выдает предупреждение

Unable to parse QML snippet: Syntax error at line 97, column 42

Фрагменты также могут содержать QML, и там также проверяется код. Если, например, в коде отсутствует фигурная скобка, QDoc выдает предупреждение

Unable to parse QML snippet: Expected token '{' at line 63, column 52

QDoc часто не может проанализировать неполные фрагменты QML; в таких случаях часто достаточно заменить команды \qml ... \endqml на \code ... \endcode, чтобы подавить это предупреждение.

Команда <command> завершилась неудачей в конце файла <filename>

Пример:

Command "\snippet (//! [2]) failed at end of file qmlbars/qml/qmlbars/main.qml".

В этом случае предупреждение означает, что команда \snippet не нашла второй метки "//! [2]" для обозначения конца фрагмента. Также это может означать, что в этом файле фрагмента не было найдено ни одного вхождения этой метки фрагмента.

Другой пример:

Command '\skipto' failed at end of file 'styling/CMakeLists.txt".

Команда \skipto + <pattern> перемещает курсор к следующей строке, содержащей этот шаблон. Если \skipto его не найдет, QDoc выдает это предупреждение.

Не удалось открыть <file> для записи

Это предупреждение ясно означает, что невозможно открыть файл для записи, вероятно, из-за неправильного пути или разрешения на запись в определенном каталоге.

Это название страницы существует в более чем одном файле

Команда \title устанавливает заголовок страницы.

\page activeqt-server.html
\title Building ActiveX servers in Qt

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

Содержание слишком длинное

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

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

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

Максимальное количество символов для одного токена показано вместе с предупреждением, например:

file.qdoc:71154: (qdoc) warning: The content is too long.

[The maximum amount of characters for this content is 524288.
Consider splitting it or reducing its size.]

См. также Невозможно найти файл включения qdoc <filename> и Невозможно открыть файл для цитирования: <filename>.