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

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

Примечание: Хотя большинство этих команд предназначены для отображения кода 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 принимает необязательные параметры.