Разметка текста

Команды форматирования текста указывают, как должен отображаться текст.

\a (маркер параметра)

Команда \a сообщает QDoc, что следующее слово — имя формального параметра.

Если формальный параметр не задокументирован или написан неправильно, выдаётся предупреждение. Поэтому, при документировании функции, следует указывать каждый формальный параметр по имени в описании функции, предваряя его командой \a. Имя параметра затем отображается курсивом.

/ *!
   Constructs a line edit containing the text
   \a contents. The \a parent parameter is sent
   to the QWidget constructor.
* /

QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)
{
   ...
}

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

QLineEdit::QLineEdit ( const QString & contents, QWidget *parent )

Создаёт поле ввода, содержащее текст contents. Параметр parent передаётся конструктору QWidget.

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

\c (шрифт кода)

Команда \c используется для отображения имён переменных, имён пользовательских классов и ключевых слов C++ (например, int и for) в шрифте кода.

Команда отображает свой аргумент с помощью шрифта с фиксированной шириной. Например:

/ *!
  The \c AnalogClock class provides a clock widget with hour
  and minute hands that is automatically updated every
  few seconds.
* /

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

Класс AnalogClock предоставляет виджет часов с часовой и минутной стрелками, которые автоматически обновляются каждые несколько секунд.

Если текст, который должен быть отображён в шрифте кода, содержит пробелы, заключите весь текст в фигурные скобки.

\c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}

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

QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)

Команда \c принимает специальный символ \ в своём аргументе, который отображает его как обычный символ. Таким образом, если вы хотите использовать вложенные команды, вы должны использовать команду телетипа (\tt) вместо неё.

См. также \tt и \code.

\div

Команды \div и \enddiv ограничивают большой или малый блок текста (который может включать другие команды QDoc), к которому должны быть применены специальные атрибуты форматирования.

Аргумент должен быть указан в фигурных скобках, как в комментарии QDoc, показанном ниже. Аргумент не интерпретируется, но используется в качестве атрибута(ов) тега, который выводит QDoc.

Например, мы можем захотеть отобразить изображение в строке так, чтобы оно плавало справа от текущего блока текста:

/ *!
   \div {class="float-right"}
     \inlineimage qml-column.png
   \enddiv

* /

Если QDoc генерирует HTML, он преобразует эти команды в:

<div class="float-right"><p><img src="images/qml-column.png" /></p></div>

Для HTML значение атрибута float-right затем будет относиться к фрагменту в файле style.css, который в этом случае может быть:

div.float-right
{
   float: right; margin-left: 2em
}

Ниже приведён пример, взятый из файла index.qdoc, используемого для генерации index.html для Qt 4.7:

\div {class="indexbox guide"}
    \div {class="heading"}
        Qt Developer Guide
\enddiv
    \div {class="indexboxcont indexboxbar"}
        \div {class="section indexIcon"} \emptyspan
        \enddiv
        \div {class="section"}
            Qt is a cross-platform application and UI
            framework. Using Qt, you can write web-enabled
            applications once and deploy them across desktop,
            mobile and embedded operating systems without
            rewriting the source code.
        \enddiv
        \div {class="section sectionlist"}
            \list
               \li \l{Getting Started}
               \li \l{Installation} {Installation}
               \li \l{how-to-learn-qt.html} {How to learn Qt}
               \li \l{tutorials.html} {Tutorials}
               \li \l{Qt Examples} {Examples}
               \li \l{qt4-7-intro.html} {What's new in Qt 4.7}
            \endlist
        \enddiv
    \enddiv
\enddiv

Когда все значения атрибутов класса определены так, как они указаны в файле style.css, который используется для отображения документации Qt, вышеупомянутый пример отображается как:

См. также \span.

\span

Команда \span применяет специальное форматирование к небольшому блоку текста.

Должны быть предоставлены два аргумента, каждый в фигурных скобках, как показано в комментарии QDoc ниже. Первый аргумент не интерпретируется, а указывает атрибут(ы) форматирования тега, выводимого QDoc. Второй аргумент — текст, который должен быть отображён со специальными атрибутами форматирования.

Например, мы можем захотеть отобразить первое слово каждого элемента в числовом списке синим цветом.

/ *!
    Global variables with complex types:
\list 1
        \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14
        \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15
        \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16
        \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17
    \endlist
* /

Класс variableName относится к фрагменту в вашем файле style.css.

.variableName
{
    font-family: courier;
color: blue
}

Используя указанный выше фрагмент variableName, пример отображается как:

Глобальные переменные со сложными типами:

1. mutableComplex1 в globals.cpp на строке 14
2. mutableComplex2 в globals.cpp на строке 15
3. constComplex1 в globals.cpp на строке 16
4. constComplex2 в globals.cpp на строке 17

См. также \div.

\tt (шрифт телетайпа)

Команда \tt отображает свой аргумент с помощью шрифта с фиксированной шириной. Эта команда работает так же, как и команда \c, за исключением того, что \tt позволяет вкладывать команды QDoc в аргумент (например, \e, \b и \underline).

/ *!
    After having populated the main container with
    child widgets, \c setupUi() scans the main container's list of
    slots for names with the form
    \tt{on_\e{objectName}_\e{signalName}().}
* /

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

После заполнения основного контейнера дочерними виджетами, setupUi() сканирует список слотов основного контейнера для имён с формой on_objectName_signalName().

Если текст, который должен быть отображён в шрифте кода, содержит пробелы, заключите весь текст в фигурные скобки.

\tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}

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

QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)

См. также \c.

\b

Команда \b отображает свой аргумент жирным шрифтом. Эта команда раньше называлась \bold.

/ *!
    This is regular text; \b {this text is
    rendered using the \\b command}.
* /

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

Это обычный текст; этот текст отображается с помощью команды \b.

\e (выделение, курсив)

Команда \e отображает свой аргумент в специальном шрифте, обычно курсивом. Эта команда раньше называлась \i, которая теперь устарела.

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

/ *!
    Here, we render \e {a few words} in italics.
* /

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

Здесь мы отображаем несколько слов курсивом.

Если вы хотите использовать другие команды QDoc в аргументе, содержащем пробелы, вам всегда необходимо заключить аргумент в фигурные скобки. Но QDoc достаточно умен, чтобы подсчитать скобки [3], поэтому вам не нужны фигурные скобки в таких случаях:

/ *!
    An argument can sometimes contain whitespaces,
    for example: \e QPushButton(tr("A Brand New Button"))
* /

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

Аргумент иногда может содержать пробелы, например: QPushButton(tr("Новая кнопка"))

Наконец, знаки препинания в конце не включаются в аргумент [4], так же как и "'s" [5]

\sub

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

/ *!
    Definition (Range): Consider the sequence
    {x\sub n}\sub {n > 1} . The set

    {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...}

    is called the range of the sequence.
* /

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

Определение (Диапазон): Рассмотрим последовательность {x_n}_{n > 1}. Множество

{x₂, x₃, x₄, ...} = {x_n ; n = 2, 3, 4, ...}

называется диапазоном последовательности.

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

\sup

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

/ *!
    The series

    1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ...

    is called the \i {geometric series}.
* /

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

Ряд

1 + a + a² + a³ + a⁴ + ...

называется геометрическим рядом.

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

\uicontrol

Команда \uicontrol используется для маркировки содержимого как используемого для элементов управления UI. При использовании HTML вывод отображается жирным шрифтом.

\underline

Команда \underline отображает свой аргумент подчеркнутым.

/ *!
    The \underline {F}ile menu gives the users the possibility
    to edit an existing file, or save a new or modified
    file, and exit the application.
* /

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

Меню Файл предоставляет пользователям возможность редактировать существующий файл, сохранять новый или изменённый файл и завершать работу приложения.

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

\\ (двойной обратный слэш)

Команда \\ расширяется до двойного обратного слэша.

Команды QDoc всегда начинаются с одного обратного слэша. Чтобы отобразить один обратный слэш в тексте, необходимо набрать два обратных слэша. Если вы хотите отобразить два обратных слэша, вам нужно набрать четыре.

/ *!
    The \\\\ command is useful if you want a
    backslash to appear verbatim, for example,
    writing C:\\windows\\home\\.
* /

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

Команда \\ полезна, если вы хотите отобразить обратный слэш буквально, например, при написании C:\windows\home\.

Однако, если вы также хотите, чтобы ваш текст отображался в шрифте с фиксированной шириной, вы можете использовать команду \c вместо неё, которая принимает и отображает обратный слэш как любой другой символ. Например:

/ *!
    The \\c command is useful if you want a
    backslash to appear verbatim, and the word
    that contains it written in a monospace font,
    like this: \c {C:\windows\home\}.
* /

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

Команда \c полезна, если вы хотите отобразить обратный слэш буквально, а слово, которое его содержит, отобразить в шрифте с фиксированной шириной, например: C:\windows\home\.

См. также \b.