Разное

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

\annotatedlist

Команда \annotatedlist расширяется до списка членов группы, каждый член перечислен с его кратким описанием. Ниже приведен пример из документации Qt Reference:

/ *!
    ...
    \section1 Drag and Drop Classes

    These classes deal with drag and drop and the necessary mime type
    encoding and decoding.

    \annotatedlist draganddrop

* /

Это генерирует список всех C++ классов и/или QML типов в группе draganddrop. C++ класс или QML тип в группе draganddrop будет содержать \ingroup draganddrop в своем комментарии \class или \qmltype.

\qtcmakepackage

Используйте команду \qtcmakepackage, чтобы добавить информацию о пакете CMake к классам и именам пространств. Эта информация будет отображаться в таблице в верхней части страницы документации класса или пространства имен. Например:

/ *!
    \namespace Foo
    \inheaderfile Bar
    \qtcmakepackage Baz
    \brief A namespace.

    [...]
* /

QDoc выведет это как

Пространство имен Foo

Пространство имен. Подробнее...

\generatelist

Команда \generatelist расширяется до списка ссылок на сущности документации в группе. Ниже приведен пример из документации Qt Reference:

/ *!
    \page classes.html
    \title All Classes

    For a shorter list that only includes the most
    frequently used classes, see \l{Qt's Main Classes}.

    \generatelist classes Q
* /

Это создает страницу Все классы. Команда принимает следующие аргументы:

annotatedclasses

Аргумент annotatedclasses предоставляет таблицу, содержащую имена всех классов и описание каждого класса. Каждое имя класса является ссылкой на документацию по классу. Например:

Класс C++ документируется с помощью команды \class. Аннотация для класса взята из аргумента команды \brief комментария к классу.

annotatedexamples

Аргумент annotatedexamples предоставляет полный список всех примеров в виде набора таблиц, содержащих заголовки всех примеров и описание каждого примера. Каждый заголовок является ссылкой на документацию примера.

Для каждого модуля (который имеет документированные примеры) генерируется отдельная таблица, при условии, что модуль определил переменную конфигурации navigation.landingpage. Переменная landingpage используется в качестве заголовка для заголовка, предваряющего каждую таблицу.

annotatedattributions

Аргумент annotatedattributions предоставляет полный список всех ссылок в виде набора таблиц, содержащих заголовки всех ссылок и описание каждой ссылки. Каждый заголовок — ссылка на страницу атрибуции.

Для каждого модуля (который имеет ссылки) генерируется отдельная таблица, при условии, что модуль определил переменную конфигурации navigation.landingpage. Переменная landingpage используется в качестве заголовка для заголовка, предваряющего каждую таблицу.

classes <prefix>

Аргумент classes предоставляет полный алфавитный список классов. Второй аргумент, <prefix>, — общий префикс для имён классов. Имена классов будут сортироваться по символу, следующему за общим префиксом. Например, общим префиксом для классов Qt является Q. Аргумент общего префикса является необязательным. Если общий префикс не указан, имена классов будут сортироваться по первому символу.

Каждое имя класса становится ссылкой на документацию по данному классу. Эта команда используется для создания страницы Все классы следующим образом:

/ *!
    \page classes.html
    \title All Classes
    \ingroup classlists

    \brief Alphabetical list of classes.

    This is a list of all Qt classes. For classes that
    have been deprecated, see the \l{Obsolete Classes}
    list.

    \generatelist classes Q
* /

Класс C++ документируется с помощью команды \class.

classesbymodule

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

Например, эту команду можно использовать на странице модуля следующим образом:

/ *!
    \page phonon-module.html
    \module Phonon
    \title Phonon Module
    \ingroup modules

    \brief Contains namespaces and classes for multimedia functionality.

    \generatelist{classesbymodule Phonon}

...

* /

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

qmltypesbymodule

Аналогично аргументу classesbymodule, но используется для перечисления типов QML из модуля QML, указанного со вторым аргументом.

Примечание: Поддержка этого аргумента была добавлена в QDoc 5.6.

jstypesbymodule

Аналогично аргументу classesbymodule, но используется для перечисления типов JavaScript из указанного со вторым аргументом модуля.

Примечание: Поддержка этого аргумента была добавлена в QDoc 5.6.

examplefiles [regular_expression]

Аргумент examplefiles перечисляет файлы, которые являются частью проекта примера. Необязательный второй аргумент — регулярное выражение; если он указан, перечисляются только файлы, путь к которым соответствует регулярному выражению.

Аргумент examplefiles может использоваться только в документации примера (см. \example) и обычно используется вместе с командой \noautolist.

exampleimages [regular_expression]

Аргумент exampleimages перечисляет изображения, которые являются частью проекта примера. Необязательный второй аргумент — регулярное выражение; если он указан, перечисляются только файлы изображений, путь к которым соответствует регулярному выражению.

Аргумент exampleimages может использоваться только в документации примера (см. \example) и обычно используется вместе с командой \noautolist.

functionindex

Аргумент functionindex предоставляет полный алфавитный список всех документированных функций-членов. Обычно используется только для генерации страницы Индекс функций Qt следующим образом:

/ *!
    \page functions.html
    \title All Functions
    \ingroup funclists

    \brief All documented Qt functions listed alphabetically with a
    link to where each one is declared.

    This is the list of all documented member functions and global
    functions in the Qt API. Each function has a link to the
    class or header file where it is declared and documented.

    \generatelist functionindex
* /

legalese

Аргумент legalese указывает QDoc на генерацию списка лицензий в текущем проекте документации. Каждая лицензия идентифицируется с помощью команды \legalese.

overviews

Аргумент overviews используется для указания QDoc на генерацию списка путём конкатенации содержимого всех страниц \group. Qt использует его для создания страницы обзоры таким образом:

/ *!
    \page overviews.html

    \title All Overviews and HOWTOs

    \generatelist overviews
* /

attributions

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

related

Аргумент related используется в сочетании с командами \group и \ingroup для перечисления всех обзоров, относящихся к указанной группе. Например, страница для страницы Программирование с помощью Qt генерируется следующим образом:

/ *!
    \group qt-basic-concepts
    \title Programming with Qt

    \brief The basic architecture of the Qt cross-platform application and UI framework.

    Qt is a cross-platform application and UI framework for
    writing web-enabled applications for desktop, mobile, and
    embedded operating systems. This page contains links to
    articles and overviews explaining key components and
    techniuqes used in Qt development.

    \generatelist {related}
* /

Каждая страница, перечисленная на этой странице группы, содержит команду:

\ingroup qt-basic-concepts

\if

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

Команда считывает остальную часть строки и анализирует её как оператор C++ #if.

/ *!
    \if defined(opensourceedition)

    \note This edition is for the development of
    \l{Qt Open Source Edition} {Free and Open Source}
    software only; see \l{Qt Commercial Editions}.

    \endif
* /

Этот комментарий QDoc будет отображен только в том случае, если препроцессорный символ opensourceedition определён и указан в переменной defines в файле конфигурации, чтобы QDoc обрабатывал код внутри #ifdef и #endif:

defines = opensourceedition

Вы также можете определить препроцессорный символ вручную в командной строке. Дополнительную информацию см. в документации по переменной defines.

См. также \endif, \else, defines и falsehoods.

\endif

Команда \endif и соответствующая команда \if заключают части комментария QDoc, которые будут включены, если условие, указанное в аргументе команды \if, истинно.

Дополнительную информацию см. в документации по команде \if.

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

\else

Команда \else определяет альтернативу, если условие в команде \if ложно.

Команда \else может использоваться только в командах \if...\endif, но полезна, когда существует только две альтернативы.

\include

Команда \include отправляет весь или часть файла, указанного её первым аргументом, в поток ввода QDoc для обработки в качестве фрагмента комментария QDoc.

Команда полезна, когда какой-либо фрагмент команд или текста требуется использовать в нескольких местах документации. Используйте команду \include везде, где вы хотите вставить фрагмент в документацию. Файл, содержащий фрагмент для включения, должен находиться в пути(ях), указанных в переменной конфигурации QDoc sourcedirs или exampledirs. Он может быть любым исходным файлом, анализируемым QDoc (или даже тем же, где используется команда \include), или любым текстовым файлом. Чтобы хранить фрагменты в отдельном файле, который не предназначен для анализа QDoc, используйте расширение файла, которое не указано в sources.fileextensions; например, .qdocinc.

Команда может иметь один или два аргумента. Первый аргумент всегда — имя файла. Содержимое файла должно быть входными данными QDoc, то есть последовательностью команд QDoc и текста, но без заключительных разделителей комментария QDoc /*! ... */. Если вы хотите включить весь файл с указанным именем, не используйте второй аргумент. Если вы хотите включить только часть файла, см. форму с двумя аргументами ниже. Вот пример формы с одним аргументом:

/ *!
    \page corefeatures.html
    \title Core Features

    \include examples/signalandslots.qdocinc
    \include examples/objectmodel.qdocinc
    \include examples/layoutmanagement.qdocinc
* /

QDoc отображает эту страницу как показано здесь.

\include filename snippet-identifier

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

    //! [snippet-id1]

       QDoc commands and text...

//! [snippet-id1]

    //! [snippet-id2]

       More QDoc commands and text...

//! [snippet-id2]

Затем вы можете использовать двухаргументную форму команды:

\input examples/signalandslots.qdocinc snippet-id2
\input examples/objectmodel.qdocinc another-snippet-id

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

Примечание: Идентификаторы фрагментов работают и внутри блоков комментариев к документации (/*! .. */), поэтому нет необходимости использовать отдельный .qdocinc файл. При обработке блока комментариев QDoc удаляет любые //! строки комментариев из генерируемого вывода.

\meta

Команда \meta используется для добавления метаданных в документацию примеров и при генерации HTML-вывода для указания авторов класса C++.

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

/ *!
    \class QWidget
    \brief The QWidget class is the base class of all user interface objects.

    \ingroup basicwidgets

    \meta {technology} {User Interface}
    \meta {platform} {macOS 10.6}
    \meta {platform} {MeeGo}
    \meta {audience} {user}
    \meta {audience} {programmer}
    \meta {audience} {designer}
* /

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

Пример метаданных

Другое применение команды \meta — включение метаданных (тегов) в \example документацию. По умолчанию QDoc генерирует теги примера на основе \title примера и имени модуля. Эти теги отображаются в режиме «Добро пожаловать» Qt Creator, помогая пользователям перемещаться по списку примеров.

Дополнительные теги могут быть созданы с помощью \\meta {tag} {tag1,[tag2,...]}. Например:

/ *!
    \example helloworld
    \title Hello World Example
    \meta {tag} {tutorial,basic}
* /

Это приведет к появлению следующих тегов: tutorial,basic,hello,world. Общие слова, такие как example, игнорируются.

Исключение примеров

Отметив пример как нерабочий, вы исключите его из генерируемого файла манифеста, фактически удалив его из режима «Добро пожаловать» Qt Creator.

\meta tag broken

Примеры путей установки

Команда \meta в сочетании с аргументом installpath указывает расположение установленного примера. Это значение переопределяет значение, заданное с помощью переменной конфигурации examplesinstallpath.

/ *!
    \example helloworld
    \title Hello World Example
    \meta {installpath} {tutorials}
* /

См. также examplesinstallpath.

\noautolist

Команда \noautolist указывает, что автоматически генерируемый список классов C++ или типов QML в нижней части страницы модуля C++ или QML должен быть опущен, так как классы или типы были перечислены вручную. Эту команду также можно использовать с командой \group для пропуска списка членов группы, когда они перечислены вручную.

Команда должна стоять на отдельной строке. См. Типы QML Qt Quick Controls для примера. Страница сгенерирована из qtquickcontrols2-qmlmodule.qdoc. Там вы найдете комментарий QDoc, содержащий команду \qmlmodule для модуля QtQuick.Controls. Тот же комментарий содержит команду \noautolist для отключения автоматической генерации списка и \generatelist для перечисления типов QML в определённом разделе документа.

Эта команда была введена в QDoc 5.6.

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

\omit

Команды \omit и \endomit ограничивают части документации, которые вы хотите пропустить в QDoc. Например:

/ *!
    \table
    \row
        \li Basic Widgets
        \li Basic GUI widgets such as buttons, comboboxes
           and scrollbars.

    \omit
    \row
        \li Component Model
        \li Interfaces and helper classes for the Qt
           Component Model.
    \endomit

    \row
        \li Database Classes
        \li Database related classes, e.g. for SQL databases.
    \endtable
* /

QDoc отобразит это следующим образом:

\raw (avoid)

Команда \raw и соответствующая команда \endraw ограничивают блок кода языка разметки.

Примечание: По возможности избегайте использования этой команды. Если вы пытаетесь получить особую таблицу или поведение списка, попробуйте добиться нужного поведения с помощью команд \span и \div в командах \table или \list.

Команда принимает аргумент, указывающий формат кода. В настоящее время поддерживается только формат HTML.

Команда \raw полезна, если вы хотите использовать некоторые особые HTML-эффекты в вашей документации.

/ *!
    Qt has some predefined QColor objects.

    \raw HTML
    <style type="text/css" id="colorstyles">
    #color-blue { background-color: #0000ff; color: #ffffff }
    #color-darkBlue { background-color: #000080; color: #ffffff }
    #color-cyan { background-color: #00ffff; color: #000000 }
    </style>

    <p>
    <tt id="color-blue">Blue(#0000ff)</tt>,
    <tt id="color-darkBlue">dark blue(#000080)</tt> and
    <tt id="color-cyan">cyan(#00ffff)</tt>.
</p>
    \endraw
* /

QDoc отобразит это следующим образом:

Qt имеет некоторые предопределённые объекты QColor.

Синий(#0000ff), тёмно-синий(#000080) и голубой(#00ffff).

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

\tt {\span {id="color-blue"} {Blue(#0000ff)}},
\tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and
\tt {\span {id="color-cyan"} {cyan(#00ffff)}}.

...что отобразится как:

Blue(#0000ff), dark blue(#000080) и cyan(#00ffff).

\unicode

Команда \unicode позволяет вставлять произвольный символ Unicode в документ.

Команда принимает аргумент, указывающий символ как целое число. По умолчанию предполагается основание 10, если не указан префикс '0x' или '0' (соответственно для оснований 16 и 8). Например:

O G\unicode{0xEA}nio e as Rosas

\unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour

\unicode 0x3A3 \e{a}\sub{\e{i}}

QDoc отобразит это следующим образом:

O Gênio e as Rosas

À table en famille avec 15 € par jour

Σ a_i