Разное

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

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

\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 a list of the classes
    provided for compatibility with Qt3, see \l{Qt3 Support
    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 в его комментарии \class.

qmltypesbymodule

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

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

jstypesbymodule

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

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

compatclasses

Аргумент compatclasses генерирует список поддерживаемых классов в алфавитном порядке. Обычно используется только для генерации страницы Qt3 Поддерживаемые классы таким образом:

/ *!
    \page compatclasses.html
    \title Qt3 Support Classes
    \ingroup classlists

    \brief Enable porting of code from Qt 3 to Qt 4.

    These are the classes that Qt provides for compatibility with Qt
    3. Most of these are provided by the Qt3Support module.

    \generatelist compatclasses
* /

Поддерживаемый класс идентифицируется в комментарии \class с помощью команды \compat.

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, но полезна, когда есть только два варианта.

/ *!
    The Qt 3 support library is provided to keep old
    source code working.

    In addition to the \c Qt3Support classes, Qt 4 provides
    compatibility functions when it's possible for an old
    API to cohabit with the new one.

    \if !defined(QT3_SUPPORT)
        \if defined(QT3_SUPPORTWARNINGS)
            The compiler emits a warning when a
            compatibility function is called. (This works
            only with GCC 3.2+ and MSVC 7.)
        \else
            To use the Qt 3 support library, you need to
            have the line QT += qt3support in your .pro
            file (qmake automatically define the
            QT3_SUPPORT symbol, turning on compatibility
            function support).

            You can also define the symbol manually (for example,
            if you don't want to link against the \c
            Qt3Support library), or you can define \c
            QT3_SUPPORT_WARNINGS instead, telling the
            compiler to emit a warning when a compatibility
            function is called. (This works only with GCC
            3.2+ and MSVC 7.)
        \endif
    \endif
* /

Если QT3_SUPPORT определено, комментарий будет отображен так:

Библиотека поддержки Qt 3 предоставляется для сохранения работоспособности старого исходного кода.

В дополнение к классам Qt3Support, Qt 4 предоставляет функции совместимости, когда это возможно для старого API сосуществовать с новым.

Если QT3_SUPPORT не определено, но QT3_SUPPORT_WARNINGS определено, комментарий будет отображен так:

Библиотека поддержки Qt 3 предоставляется для сохранения работоспособности старого исходного кода.

В дополнение к классам Qt3Support, Qt 4 предоставляет функции совместимости, когда это возможно для старого API сосуществовать с новым.

Компилятор выводит предупреждение при вызове функции совместимости. (Это работает только с GCC 3.2+ и MSVC 7.)

Если ни один из символов не определен, комментарий будет отображен так

Библиотека поддержки Qt 3 предоставляется для сохранения работоспособности старого исходного кода.

В дополнение к классам Qt3Support, Qt 4 предоставляет функции совместимости, когда старая API может сосуществовать с новой.

Для использования библиотеки поддержки Qt 3 необходимо добавить строку QT += qt3support в ваш файл .pro (qmake автоматически определяет символ QT3_SUPPORT, включающий поддержку функций совместимости).

Вы также можете определить символ вручную (например, если вы не хотите ссылаться на библиотеку Qt3Support), или вы можете определить QT3_SUPPORT_WARNINGS, сообщив компилятору выдать предупреждение при вызове функции совместимости. (Это работает только с GCC 3.2+ и MSVC 7.)

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

\include

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

Команда полезна, когда какой-то фрагмент команд или текста необходимо использовать в нескольких местах документации. Используйте команду \include везде, где хотите вставить фрагмент в документацию. Файл, содержащий фрагмент для включения, должен находиться в пути(ях), указанных в переменной конфигурации QDoc sourcedirs. Это может быть любой исходный файл, анализируемый 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 в основном используется для включения метаданных в файлы DITA XML. Она также используется для добавления метаданных к примерам документации и при генерации 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, приведенный выше пример не повлияет на сгенерированный вывод, но если вы запустите QDoc для генерации DITA XML, пример сгенерирует следующее:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cxxClass PUBLIC "-//NOKIA//DTD DITA C++ API Class Reference Type v0.6.0//EN" "dtd/cxxClass.dtd">
<!--qwidget.cpp-->
<cxxClass id="id-9a14268e-6b09-4eee-b940-21a00a0961df">
   <apiName>QWidget</apiName>
   <shortdesc>the QWidget class is the base class of all user interface objects.</shortdesc>
   <prolog>
       <author>Qt Development Frameworks</author>
       <publisher>Qt Project</publisher>
       <copyright>
           <copyryear year="2018"/>
           <copyrholder>Qt Project</copyrholder>
       </copyright>
       <permissions view="all"/>
       <metadata>
           <audience type="designer"/>
           <audience type="programmer"/>
           <audience type="user"/>
           <category>Class reference</category>
           <prodinfo>
               <prodname>Qt Reference Documentation</prodname>
               <vrmlist>
                   <vrm version="4" release="7" modification="3"/>
               </vrmlist>
               <component>QtGui</component>
           </prodinfo>
           <othermeta name="platform" content="MeeGo"/>
           <othermeta name="platform" content="macOS 10.6"/>
           <othermeta name="technology" content="User Interface"/>
       </metadata>
   </prolog>

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

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

Еще одно применение команды \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, игнорируются.

\noautolist

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

Команда должна стоять на отдельной строке. См. Qt Sensors QML Types для примера. Страница сгенерирована из qtsensors5.qdoc. Там вы найдете комментарий qdoc, содержащий команду \qmlmodule для модуля QtSensors. Тот же комментарий qdoc содержит две команды \annotated-list для перечисления типов QML в двух отдельных группах. Типы QML были разделены на эти две группы, потому что это имеет больше смысла, чем перечисление их в одном алфавитном списке. В конце комментария использовался \noautolist чтобы указать qdoc не генерировать автоматический аннотированный список.

Эта команда была представлена в 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 размечают блок исходного кода языка разметки.

Примечание: Избегайте использования этой команды, если возможно, так как она генерирует код DITA XML, вызывающий проблемы. Если вы пытаетесь получить специальное поведение таблиц или списков, попробуйте получить желаемое поведение с помощью команд \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 позволяет вставлять произвольный символ Юникода в документ.

Команда принимает аргумент, указывающий символ как целое число. По умолчанию предполагается основание 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