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

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

\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
}

Примечание: Обратите внимание, что команда \div может быть вложена.

Ниже приведён пример из файла 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

Примечание: Команда span не приводит к началу нового абзаца.

См. также \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 используется для маркирования контента, используемого для элементов управления пользовательским интерфейсом. При использовании 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.