Включение кода в строку

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

Примечание: Хотя большинство этих команд предназначены для отображения кода C++, команды \snippet и \codeline предпочтительнее других. Эти команды позволяют подставлять эквивалентные фрагменты кода для других языковых связок Qt вместо фрагментов C++ в документации.

\code

Команды \code и \endcode заключают фрагмент исходного кода.

Примечание: Команда \c может использоваться для коротких фрагментов кода в предложении. Команда \code предназначена для более длинных фрагментов кода. Она отображает код дословно в отдельном абзаце в элементе html <pre> и анализирует заключенный фрагмент, создавая ссылки на все известные типы в коде.

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

При обработке любой из команд \code, \newcode или \oldcode, QDoc удаляет все отступы, которые являются общими для блоков кода verbatim в пределах /*! ... */ комментария перед добавлением стандартных отступов.

Примечание: Это не относится к внешним цитируемым фрагментам кода, использующим команду \quotefromfile или \quotefile.

/ *!
    \code
        #include <QApplication>
        #include <QPushButton>

        int main(int argc, char *argv[])
        {
            ...
        }
    \ endcode
* /

QDoc отображает это как:

#include <QApplication>
#include <QPushButton>

int main(int argc, char *argv[])
{
    ...
}

Другие команды QDoc отключены в \code... \endcode, и специальный символ '\' принимается и отображается как остальной код, если за ним не следует цифра и параметрам не были переданы в \code.

Параметры фрагмента кода

Начиная с версии QDoc 5.12, команда \code также принимает необязательные параметры. Параметры полезны для вставки простых строк в фрагмент кода. Чтобы вставить строку в определенное место в фрагменте, добавьте обратную косую черту, за которой следует цифра (1..8). Цифры соответствуют порядку списка аргументов, где аргументы разделены пробелами.

Например:

/ *!
\code * hello
/\1 \2 \1/
\ endcode
* /

Для приведенного выше фрагмента QDoc отображает слово hello, заключенное в комментарий в стиле C.

Включение кода из внешних файлов

Чтобы включить фрагменты кода из внешнего файла, используйте команды \snippet и \codeline.

См. также \c, \badcode, \quotefromfile, \newcode и \oldcode.

\badcode

Аналогично \code, команды \badcode и \endcode заключают содержимое, которое отображается дословно в отдельном абзаце, но никакой анализ или автоматическое создание ссылок не выполняется. Вместо этого содержимое обрабатывается как обычный текст.

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

Как и \code, \badcode также принимает необязательные параметры.

\newcode

Команды \newcode, \oldcode и \endcode позволяют показать, как перенести фрагмент кода в новую версию API.

Команда \newcode и ее партнер \oldcode — это удобное сочетание команд \code: это сочетание предоставляет текст, связывающий два фрагмента кода друг с другом.

Команда \newcode требует предшествующей команды \oldcode.

Как и команда \code, команда \newcode отображает свой код на новой строке в документации с помощью шрифта с фиксированной шириной и стандартными отступами.

/ *!
    \oldcode
        if (printer->setup(parent))
            ...
    \newcode
        QPrintDialog dialog(printer, parent);
            if (dialog.exec())
                ...
    \ endcode
* /

QDoc отображает это как:

Например, если у вас есть код, подобный

if (printer->setup(parent))
    ...

вы можете переписать его как

QPrintDialog dialog(printer, parent);
    if (dialog.exec())
        ...

Другие команды QDoc отключены внутри \oldcode ... \endcode, и символ '\' не нужно экранировать.

\oldcode

Команда \oldcode требует соответствующей команды \newcode; в противном случае QDoc не сможет обработать команду и выдаст предупреждение.

См. также \newcode.

\qml

Команды \qml и \endqml заключают фрагмент QML исходного кода.

/ *!
    \qml
        import QtQuick 2.0

        Row {
            Rectangle {
                width: 100; height: 100
                color: "blue"
                transform: Translate { y: 20 }
            }
            Rectangle {
                width: 100; height: 100
                color: "red"
                transform: Translate { y: -20 }
            }
        }
    \endqml
* /

QDoc отображает это как:

import QtQuick 2.0

Row {
    Rectangle {
        width: 100; height: 100
        color: "blue"
        transform: Translate { y: 20 }
    }
    Rectangle {
        width: 100; height: 100
        color: "red"
        transform: Translate { y: -20 }
    }
}

Как и команда \code, \qml принимает необязательные параметры.