Форматирование текста

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

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