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

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

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

\code

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

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

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

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

Примечание: Это не относится к внешнему коду, цитируемому с помощью команды \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 принимает необязательные параметры.