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

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

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